BaanERP Tools Functions reference is a comprehensive guide to the functions available for developing BaanERP applications with the Baan 3GL/4GL programming language. This document describes in detail the functions available for developing BaanERP applications with the Baan 3GL/4GL programming language. Each chapter deals with a particular category of functions. The description of each function includes the syntax, overall function description, description of individual arguments, possible return values, and context. It also includes sample code for most functions.
Advertisement
Advertisement
A publication of:
Baan Development B.V.
P.O.Box 143
3770 AC Barneveld
The Netherlands
Printed in the Netherlands
© Baan Development B.V. 1998.
All rights reserved.
The information in this document is subject to change without notice. No part of this document may be reproduced, stored or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of
Baan Development B.V.
Baan Development B.V.
assumes no liability for any damages incurred, directly or indirectly, from any errors, omissions or discrepancies between the software and the information contained in this document.
Document Information
Group:
Edition:
Date:
User Documentation
A
December, 1998
Overview
Application lock features
Application lock types
Synopsis appl.delete() appl.get.user() appl.modify() appl.set()
Overview
Synopsis asc() chr$()
Overview
Audit files
Location of audit files
Audit file locking
Synopsis
Include files
Functions
aud_close_audit() aud_get_audit_dd() aud_get_col_info() aud_get_fld_values() aud_get_hdr_size() aud_get_info_seq_hdr_size() aud_open_audit() aud_read_audit_rec() aud_read_info_hdr() aud_read_info_seq_hdr() aud_read_next_audit_rec() aud_read_next_tran() aud_read_seq_hdr()
1-2
1-3
1-3
1-4
1-4
1-1
1-1
1-1
2-1
2-1
2-1
2-2
3-9
3-9
3-10
3-11
3-5
3-5
3-6
3-7
3-12
3-13
3-14
3-15
3-16
3-1
3-1
3-2
3-3
3-3
3-3
3-3
Functions reference i
Table of contents
aud_read_tran() aud_select_host() aud_update_infofile() aud_write_info_hdr() aud_write_seq_hdr()
Macros (info header)
Macros (sequence header)
Macros (transaction header)
Macros (transaction record)
Macros (transaction dates and times)
Macros (dates and times)
Sample program
Overview
Synopsis bit.and(), bit.exor(), bit.in(), bit.inv(), bit.or() bit.shiftl(), bit.shiftr()
Overview
Creating a Chart Manager client application
Synopsis chm.axis.in() chm.axis.out() chm.chartman() chm.check() chm.data.in() chm.data2domain.in() chm.delete.data() chm.delete.data2domains() chm.delete.footnotes() chm.delete.projections() chm.delete.sets() chm.disconnect() chm.domain.in() chm.domain.out() chm.draw() chm.first.data.out() chm.first.data2domain.out() chm.first.footnote.out() chm.first.projection.out() chm.first.set.out()
Functions reference ii
3-16
3-17
3-19
3-20
3-21
3-22
3-24
3-28
3-29
3-30
3-31
3-32
4-1
4-1
4-1
4-4
5-11
5-12
5-13
5-13
5-14
5-14
5-15
5-15
5-1
5-3
5-4
5-7
5-8
5-9
5-10
5-16
5-17
5-18
5-19
5-20
5-20
5-21
5-22
chm.footnote.in() chm.get.request() chm.new() chm.next.data.out() chm.next.data2domain.out() chm.next.footnote.out() chm.next.projection.out() chm.next.set.out() chm.open() chm.projection.in() chm.remove() chm.scale.axis() chm.select() chm.set.in() chm.set.option() chm.set.timer() chm.title.in() chm.title.out()
Sample program
Glossary
Overview
Synopsis bc$() bg$() box() bs$() cf$() change.window() cl.screen() cp$() cr$() cs$() current.window() data.input() del.window() delch$() deleteln$() dump.window() el$() es$() ff$()
Tahle of contents
6-8
6-9
6-9
6-13
6-7
6-7
6-8
6-8
6-3
6-4
6-5
6-5
6-1
6-1
6-3
6-13
6-14
6-14
6-14
6-15
6-15
5-29
5-30
5-31
5-31
5-33
5-34
5-35
5-35
5-22
5-23
5-25
5-25
5-26
5-27
5-28
5-29
5-36
5-36
5-37
5-39
Functions reference iii
Table of contents
fg$() first.window() fs$() get.col() get.cp() get.row() get.window.attrs() insch$() insertln$() keyin$() last.window() lf$() map.window() mark.handler() move.window() new.window() no.scroll() pc$() pf$() refresh() resize.window() scroll() set.bg.color() set.fg.color() sf$() sub.window() tab$() unmap.window() wrebuild()
Overview
Synopsis app_start() app_status() client2server() create.local.directory() remove.local.directory() remove.local.file() seq.close.local() seq.fstat.local() seq.open.local() seq.read.local()
Functions reference iv
6-24
6-24
6-25
6-26
6-26
6-27
6-27
6-27
6-28
6-28
6-29
6-29
6-29
6-19
6-20
6-21
6-21
6-22
6-22
6-23
6-23
6-16
6-16
6-17
6-17
6-17
6-18
6-18
6-19
7-6
7-7
7-7
7-8
7-10
7-3
7-4
7-5
7-6
7-1
7-1
7-2
Tahle of contents
seq.write.local() server2client()
Overview
Synopsis blue.component(), green.component(), red.component() rgb()
Overview
Synopsis compnr.check() get.company() get.compnr() switch.to.company()
Overview
Synopsis set.currencies()
Overview
New features in BaanERP
Table names and declarations
Error handling
Synopsis abort.io() abort.transaction() activate.search() commit.transaction() dal.destroy() dal.get.property.flag() dal.new() dal.set.property() dal.start.business.method() dal.update() db.bind() db.change.order() db.check.restricted() db.check.row.changed() db.check.row.domains() db.clear.table()
9-1
9-1
9-1
9-2
9-2
9-3
10-1
10-1
10-1
11-8
11-9
11-10
11-11
11-12
11-13
11-15
11-17
11-1
11-1
11-2
11-2
11-4
11-6
11-8
11-18
11-19
11-20
11-21
11-21
11-22
7-10
7-11
8-1
8-1
8-2
8-2
Functions reference v
Table of contents
db.columns.to.record() db.create.table() db.curr() db.delete() db.drop.table() db.eq() db.error() db.error.message() db.first() db.ge() db.gt() db.indexinfo() db.insert() db.last() db.le() db.lock.table() db.lt() db.next() db.nr.indices() db.nr.rows() db.permission() db.prev() db.record.to.columns() db.ref.handle.mode() db.retry.hit() db.retry.point() db.row.length() db.set.to.default() db.unbind() db.update() on.main.table() restore.rcd.main() set.limits.off() set.transaction.readonly() skip.io() store.occ.max(), store.occ.min() to.key() with.object.set.do() with.old.object.values.do()
Overview
Universal Coordinated Time
Functions reference vi
11-43
11-44
11-44
11-45
11-45
11-46
11-47
11-48
11-37
11-37
11-38
11-39
11-39
11-41
11-42
11-42
11-49
11-49
11-50
11-51
11-52
11-53
11-54
11-29
11-30
11-31
11-32
11-34
11-34
11-35
11-36
11-24
11-24
11-25
11-26
11-26
11-27
11-28
11-29
12-1
12-1
Time zones
Week handling
Synopsis choose.time.zone.from.list() date.num() date.to.date() date.to.inputstr$() date.to.num() date.to.utc() dte$() get.time.zone() inputstr.to.date() inputstr.to.utc() input.to.utc() local.to.utc() num.to.date() num.to.date$() num.to.week() set.time.zone() time.num() timezone.exists() utc.num() utc.to.date() utc.to.input() utc.to.inputstr$() utc.to.local() utc.to.week() week.to.num() week.to.utc()
Overview
Synopsis creat.tmp.file$() dir.close() dir.entry() dir.open() dir.open.tree() dir.rewind() file.chmod() file.chown() file.cp() file.mv()
Tahle of contents
12-13
12-13
12-15
12-15
12-16
12-16
12-17
12-17
12-18
12-19
12-19
12-21
12-21
12-7
12-8
12-9
12-9
12-10
12-11
12-11
12-12
12-1
12-1
12-2
12-4
12-4
12-5
12-6
12-7
13-1
13-1
13-3
13-4
13-4
13-5
13-6
13-7
13-7
13-9
13-9
13-10
Functions reference vii
Table of contents
file.mv.across.hosts() file.rm() file.stat() fstat.info() getcwd() mkdir() pathname() rmdir() seq.clearerr() seq.close() seq.eof() seq.error() seq.flush() seq.getc$() seq.gets() seq.islocked() seq.lock() seq.open() seq.putc$() seq.puts() seq.read() seq.rewind() seq.seek() seq.tell() seq.ungetc$() seq.unlink() seq.unlock() seq.write() stat.info()
Overview
Synopsis exec_dll_function() exec_function() get_function() load_dll() parse_and_exec_function()
Overview
Synopsis sql.break()
Functions reference viii
14-1
14-1
14-1
14-2
14-4
14-4
14-6
15-1
15-2
15-2
13-23
13-24
13-26
13-27
13-27
13-28
13-28
13-29
13-29
13-30
13-30
13-31
13-32
13-17
13-18
13-18
13-19
13-20
13-20
13-21
13-22
13-10
13-11
13-11
13-12
13-14
13-15
13-15
13-17
sql.close() sql.exec() sql.fetch() sql.parse() sql.select.bind() sql.set.rds.full() sql.where.bind()
Overview
Synopsis ask.enum() enum.descr$() etol() ltoe() set.enum.values() set.enum.values.for.field()
Overview
Synopsis next.event() peek.event() pending.events() select.event.input() send.event()
Event types
Event array parameters
Sample program
Overview
Synopsis d.expr() expr.compile() expr.free() l.expr() s.expr$()
Overview
Synopsis add.view.field() blank.all()
Tahle of contents
16-1
16-1
16-1
16-3
16-4
16-5
16-5
16-6
15-3
15-3
15-4
15-4
15-5
15-6
15-7
17-1
17-1
17-2
17-3
17-4
17-4
17-6
17-7
17-9
17-19
18-1
18-1
18-1
18-2
18-5
18-5
18-6
19-1
19-1
19-3
19-3
Functions reference ix
Table of contents
change.field.label() check.all.input() choice.again() disable.commands()
19-4
19-5
19-5
19-6 disable.fields() 19-7 display(), display.all(), display.curr.occ(), display.fld(), display.occ() 19-9 display.total.fields() do.all.occ()
19-11
19-12 do.occ() do.occ.without.update() enable.commands() enable.fields() execute() get.field.label() get.screen.defaults() group.invisible()
19-13
19-14
19-15
19-16
19-17
19-18
19-19
19-20 input.again() inputfield.invisible() inputfield.password() inputfield.visible() is.field.invisible() make.current() mark.occ() on.old.occ() print.const() refresh.curr.occ() remove.mark() set.fields.default() stp.reset.value() to.field() to.form() to.group() update.occ()
19-26
19-27
19-28
19-28
19-29
19-29
19-30
19-31
19-32
19-20
19-21
19-22
19-22
19-23
19-24
19-24
19-25
Overview
Synopsis edit$() sprintf$() string.scan() vsprintf$()
20-1
20-1
20-1
20-4
20-10
20-12
Functions reference x
Tahle of contents
Overview
Synopsis get.argc() get.arg.type() get.double.arg(), get.long.arg(), get.string.arg() put.double.arg(), put.long.arg(), put.string.arg()
Sample program
Overview
BMS messages
Bucket messages
Synopsis
BMS messages
Bucket messages
bms.add.mask() bms.delete.mask() bms.receive$() bms.receive.buffer() bms.send() receive.bucket$() send.bucket() send.wait()
Sample programs
Overview
Using the functions
Message retrieval
Binary data transfer
sock.accept() sock.close() sock.connect() sock.flush() sock.inherit() sock.listen() sock.recv() sock.send()
Overview
Message queues
Pipes
23-1
23-1
23-2
23-2
23-3
23-4
23-5
23-7
23-8
23-9
23-10
23-11
24-1
24-1
24-2
22-4
22-4
22-5
22-6
22-8
22-9
22-9
22-11
22-1
22-1
22-2
22-3
22-3
22-3
22-3
21-1
21-1
21-2
21-2
21-3
21-3
21-4
Functions reference xi
Table of contents
Synopsis
Message queues
Pipes
close.message() open.message() pipe.clearerr() pipe.close() pipe.eof() pipe.error() pipe.flush() pipe.gets() pipe.open() pipe.puts() pipe.read() pipe.write() recv.message() send.message()
Overview
Synopsis abs() acos() asin() atan() cos() cosh() double.cmp() exp() format.round() int() log() log10() lpow() max() min() pow() round() set.fmax(), setfmin(), set.max(), set.min() sin() sinh() sqrt() table.round()
Functions reference xii
25-5
25-5
25-6
25-6
25-7
25-8
25-8
25-9
25-1
25-1
25-2
25-3
25-3
25-4
25-4
25-9
25-10
25-10
25-11
25-12
25-13
25-13
25-14
25-14
24-6
24-7
24-8
24-8
24-9
24-10
24-11
24-11
24-12
24-2
24-2
24-2
24-3
24-3
24-5
24-5
24-6
tan() tanh()
Overview
Synopsis alloc.mem() array.info() cmp.mem() copy.mem() free.mem() set.mem()
Overview
The status area of 4GL forms
Synopsis clean.mess() dal.count.error.messages() dal.get.error.message() dal.get.first.error.message() dal.reset.error.messages() dal.set.error.message() form.text$() mess() message() set.input.error() status.del() status.field() status.mess() status.off() status.on()
Overview
Synopsis mb.cast$() mb.cast.to.str$() mb.char() mb.char.info() mb.display() mb.export$() mb.ext.clean$() mb.hasbidi()
Tahle of contents
28-1
28-1
28-2
28-2
28-3
28-4
28-4
28-6
28-6
28-7
27-4
27-4
27-5
27-6
27-7
27-9
27-10
27-10
27-1
27-1
27-1
27-2
27-2
27-3
27-3
27-11
27-11
27-12
25-15
25-16
26-1
26-1
26-1
26-3
26-4
26-5
26-6
26-6
Functions reference xiii
Table of contents
mb.import$() mb.isbidi() mb.isbidi.language() mb.locale.info() mb.localename$() mb.long.to.str$() mb.nsets() mb.rev$() mb.scrpos() mb.set.info() mb.strpos() mb.tss.clean$() mb.type() mb.width()
Overview
Planning board
Activities and relations
Time scale
Plan Chart Manager events
Colors
Synopsis pcm.activate.session() pcm.change() pcm.change.object() pcm.create() pcm.create.object() pcm.destroy() pcm.destroy.object() pcm.get.data() pcm.lock() pcm.refresh() pcm.send.bms.event()
PCM_OT_MENU - menu object
PCM_OT_BUTTON – button object
PCM_OT_TIMESCALE – time scale object
PCM_OT_DELAY – delay time object
PCM_OT_COLUMN – column object
PCM_OT_ACTIVITY – activity object
PCM_OT_RELATION – relation object
PCM_OT_MARKER – marker object
Sample program
Functions reference xiv
29-11
29-11
29-12
29-13
29-14
29-15
29-16
29-17
29-18
29-20
29-22
29-23
29-3
29-4
29-5
29-5
29-8
29-9
29-9
29-10
29-1
29-1
29-1
29-1
29-2
29-2
29-3
28-7
28-8
28-9
28-9
28-10
28-10
28-11
28-11
28-13
28-13
28-14
28-15
28-15
28-16
Overview
Synopsis act.and.sleep() activate() argc() argv$() bshell.pid() kill() pstat() reactivate() signal() sleep() suspend() wait() wait.and.activate()
Overview
Synopsis get.pgrp() grab.mwindow() kill.pgrp() set.pgrp()
Overview
Synopsis create.progress.indicator() change.progress.indicator() destroy.progress.indicator()
Sample program
Overview
Synopsis random() rnd.d() rnd.i() rnd.init() srand()
Tahle of contents
32-1
32-1
32-1
32-2
32-3
32-4
31-1
31-1
31-2
31-2
31-3
31-3
33-1
33-1
33-1
33-2
33-2
33-3
33-3
30-5
30-5
30-7
30-7
30-8
30-8
30-9
30-10
30-1
30-1
30-2
30-3
30-3
30-4
30-4
Functions reference xv
Table of contents
Overview
Synopsis brp.close() brp.open() brp.open.language() brp.ready() choice.report() rprt_close() rprt_open() rprt_send()
Overview
Synopsis rsc.boolean(), rsc.double(), rsc.enum(), rsc.long(), rsc.string() rsc.font.spec() rsc.get() rsc.put() rsc.setboolean(), rsc.setdouble(), rsc.setenum(), rsc.setlong(), rsc.setstring()
Overview
Synopsis rdi.audit.hosts() rdi.column() rdi.column.combined() rdi.date.input.format$() rdi.domain() rdi.domain.byte() rdi.domain.combined() rdi.domain.date() rdi.domain.double() rdi.domain.enum() rdi.domain.enum.value() rdi.domain.float() rdi.domain.integer() rdi.domain.long() rdi.domain.set() rdi.domain.set.value() rdi.domain.string() rdi.domain.text()
35-5
36-9
36-10
36-10
36-11
36-12
36-12
36-13
36-14
36-1
36-1
36-4
36-5
36-6
36-7
36-8
36-15
36-15
36-16
36-17
36-17
34-1
34-1
34-1
34-2
34-3
34-4
34-5
34-6
34-7
34-8
35-1
35-1
35-2
35-2
35-3
35-4
Functions reference xvi
rdi.first.day.of.week() rdi.index() rdi.reference() rdi.table() rdi.table.column() tt.bobject.desc() tt.chm.appl.desc() tt.chm.application() tt.chm.chart() tt.chm.charttype() tt.company() tt.currency() tt.device() tt.field.desc() tt.index.desc() tt.language() tt.library() tt.menu.desc() tt.menu.present() tt.report.desc() tt.reportgroup.exists() tt.session.desc() tt.session.permission() tt.session.present() tt.short.field.desc() tt.table.desc() tt.user()
Overview
Synopsis qss.search() qss.sort()
Sample programs
Overview
Synopsis
Predefined variables spool.buf() spool.close() spool.line() spool.open()
Tahle of contents
38-1
38-1
38-1
38-2
38-2
38-3
38-3
37-1
37-1
37-1
37-4
37-6
36-30
36-31
36-32
36-32
36-33
36-33
36-34
36-34
36-35
36-35
36-36
36-25
36-25
36-26
36-27
36-28
36-29
36-29
36-30
36-18
36-19
36-20
36-21
36-22
36-23
36-23
36-24
Functions reference xvii
Table of contents
Overview
Building DAL query extensions
Building UI query extensions
Synopsis clear.query.extend.in.zoom() query.extend.select(), query.extend.select.in.zoom() query.extend.from(), query.extend.from.in.zoom() query.extend.where(), query.extend.where.in.zoom()
Sample program
Overview
Synopsis abort() end() exit() run.baan.prog(), run.prog() shell() start.session() stop() zoom.to$()
Overview
Synopsis concat$() isdigit() isspace() len() len.in.bytes() load.byte(), load.double(), load.float(), load.long(), load.short() lval(), val() not.fixed() pos(), rpos()
41-6
41-7
41-7
41-8 set.strip.mode(), set.symbol.strip.mode
shiftc$(), shiftl$(), shiftr$()
41-9
41-10 store.byte(), store.double(), store.float(), store.long(), store.short() 41-11 str$() 41-11 string.set$() strip$() tolower$(), toupper$() tt.align.according.domain()
41-1
41-1
41-2
41-3
41-4
41-4
41-5
41-12
41-12
41-13
41-13
40-1
40-1
40-1
40-2
40-2
40-3
40-4
40-7
40-8
40-9
39-1
39-1
39-2
39-3
39-3
39-4
39-5
39-6
39-7
Functions reference xviii
Overview
Interprocess communication (IPC)
Colors
Synopsis create.node() create.tree() create.tree.button() destroy.tree() get.tree.default() get.tree.node.dpress() get.tree.node.press() get.tree.push.button() set.node.class() set.node.class.color() set.tree.background() set.tree.font() set.tree.foreground() set.tree.linewidth() set.tree.name() view.tree()
Sample program
Overview
Dialog synchronization
Child synchronization
Example
Synopsis
Dialog synchronization
Child synchronization
set.synchronized.dialog() start.synchronized.child() start.synchronized.child.with() stop.synchronized.child() synchronize.with.child()
Sample program (child synchronization)
Overview
Synopsis bse.dir$() bse.release$()
Tahle of contents
43-4
43-5
43-6
43-7
43-7
43-8
43-1
43-1
43-2
43-2
43-4
43-4
43-4
44-1
44-1
44-1
44-2
42-6
42-7
42-7
42-8
42-8
42-9
42-10
42-11
42-1
42-1
42-2
42-2
42-4
42-5
42-5
42-11
42-12
42-13
42-14
42-15
42-16
Functions reference xix
Table of contents
bse.tmp.dir$() current.display() get.display.data() getenv$() group.exists() hostname$() is.administrator() ostype() user.exists()
Overview
Text numbers
Text field names
Committing transactions
Synopsis text.copy() text.copy.between.companies() text.copy.language() text.defaults() text.delete() text.edit() text.present.in.language() text.read() text.rewrite() text.to.buf() text.window() text.write()
Overview
Synopsis kill.timer() mtime() set.alarm() set.timer()
Overview
Synopsis create.extra.toolbar()
Functions reference xx
45-5
45-6
45-7
45-7
45-8
45-9
45-10
45-11
45-12
45-13
45-1
45-1
45-1
45-1
45-2
45-3
45-4
44-2
44-3
44-3
44-4
44-5
44-5
44-6
44-7
44-7
46-1
46-1
46-1
46-2
46-2
46-3
47-1
47-1
47-1
Overview
Synopsis at.base() at.base()
Overview
Synopsis changed() not.curr() off.change.check() on.change.check()
Sample program
Overview
Synopsis get.var() get.indexed.var() put.var() put.indexed.var() import() export()
Overview
Synopsis
Objects and subobjects change.object() change.sub.object
compress.pixmap() create.object() create.sub.object() create.sub.object.by.id() decompress.pixmap() destroy.object() destroy.sub.object() get.object() get.pixmap.info() get.sub.object() inherit.object() lower.object() map.object()
Tahle of contents
51-8
51-9
51-10
51-10
51-11
51-11
51-12
51-13
51-1
51-2
51-3
51-5
51-5
51-6
51-7
51-14
51-14
51-15
50-1
50-1
50-1
50-2
50-4
50-5
50-6
50-7
48-1
48-1
48-1
48-3
49-1
49-1
49-1
49-2
49-2
49-3
49-3
Functions reference xxi
Table of contents
Functions reference xxii
query.object() query.sub.object() raise.object() set.focus() set.sensitive() unmap.object() unset.focus() update.object()
DsCbarMenu
DsCcheckBox
DsCcolorCell
DsCcolormap
DsCcomBox, DsCdDComBox, DsClistBox, DsCdDListBox
DsCdrawnButton
DsCfield
DsCfontSet
DsCframe
DsCgc
DsCgraph
DsCgrid
DsCgwindow
DsClabel
DsCmwindow
DsCpixmap
DsCpushButton
DsCradioBox
DsCradioButton
DsCrowColumn
DsCscrollWindow
DsCscrollbar
DsCslider
DsCstatusBar
DsCtabFrame
DsCtemplate
DsCtoolBar
DsCtree
DsCgpArc
DsCgpComposite
DsCgpGroupBox
DsCgpHeader
DsCgpImage
DsCgpLine
51-81
51-83
51-85
51-87
51-91
51-92
51-94
51-97
51-41
51-42
51-46
51-62
51-68
51-72
51-73
51-79
51-99
51-101
51-102
51-105
51-114
51-117
51-118
51-120
51-122
51-124
51-22
51-26
51-28
51-29
51-30
51-34
51-35
51-39
51-15
51-18
51-19
51-19
51-20
51-20
51-21
51-21
DsCgpOleSite
DsCgpPie
DsCgpPolygon
DsCgpPolyline
DsCgpRectangle
DsCgpText
Sample program
Tahle of contents
51-126
51-129
51-132
51-135
51-138
51-141
51-143
Functions reference xxiii
Table of contents
Functions reference xxiv
This document describes in detail the functions available for developing
BaanERP applications with the Baan 3GL/4GL programming language.
In the document, functions are grouped into logical categories, such as Events,
Dynamic SQL queries, and Form and form field operations. These categories are organized alphabetically, as chapters.
Each chapter deals with a particular category of functions. The chapter provides an overview of the functionality of the functions, a synopsis of the functions, and descriptions of the individual functions, arranged alphabetically.
The description of each function includes the following elements: n n n n n
Syntax
Overall function description
Description of individual arguments
Possible return values
Context (that is, whether it is a bshell function, a 4GL library function, a 3GL library function, and so on)
For most functions, sample code is provided.
The following conventions are used in this manual:
bold
Bold type is used for the names of functions, 4GL event sections, predefined variables, objects and subobjects, when these are included in descriptive text.
italics monospace
Italics are used for argument names, when these are included in descriptive text. Italics are also used for other non-literals, for emphasis in the text, and for the titles of publications.
Monospace type is used for the syntax of functions, and for programming code.
Functions reference xxv
About this document
U7168A US BaanERP Tools: Programming Features
This document describes various Baan programming features, such as the Baan
3GL programming language, Baan 4GL language features, report scripts, database handling and Baan SQL, the Data Access Layer, the Baan Debugger, error codes, and bshell multiprocessing.
This document is available online as a Microsoft Windows help file. The help file includes the document U7168A US BaanERP Tools: Programming features.
Both the help file and the printed manuals are similarly organized. However, the help file includes numerous hypertext links to facilitate navigation, and a comprehensive index and full text search facility.
You can access the help file by choosing the Manual Pages option on the
Specific menu of the session Program Scripts (ttadv2530m000). The name of the help file is tt_mp2.hlp.
Functions reference xxvi
Use these functions to handle application locks for 4GL processes.
You use application locks to prevent other applications and users from reading and/or modifying an application’s data during critical operations. For example, to prevent access to data when it is being updated.
You can set an application lock only for the current 4GL process. You can test for or delete an application lock only within the application to which it applies.
n
Each application lock has an owner, which is automatically assigned. The owner consists of a combination of the login ID of the application user, and the process ID of the application.
n
Each application lock has a unique name, which you define when you create the lock.
n
An application lock is automatically removed when the application ends. You can also remove it with the appl.delete() function.
n
An application lock applies only to an application and that application’s data.
It is not part of the RDBMS and is not linked to a table or a particular database transaction. To set table locks, use db.lock.table().
There are three main types of application locks: n
When you set a read lock, the owner of that lock has only read access to the application’s data. Other applications can read and modify the data. Other users of the application can set read and write locks on it. But they cannot set an exclusive application lock. Each application can have several read-type application locks.
Functions reference
1-1
Application locks
n
When you set a write lock, the owner of that lock has both read and write access to the application’s data. Other applications can read the data but not modify it. Other users of the application can set read locks on it, but not a write lock or an exclusive lock. Each application can have only one writetype application lock. So you cannot set this type of lock when there is a write-type or exclusive-type lock already present.
n
When you set an exclusive lock, the owner of that lock has exclusive access to the application’s data. Other applications and users can neither read nor modify the data, nor can they set any application locks on it. You can set an exclusive lock only when there are no other locks (of any type) already present.
There is one additional lock type, which you can combine with any of the other types: n
Normally, an application lock is set for the current company only. By using this additional lock mode, you can apply the lock globally to all companies.
This means that the application lock is valid in all companies.
long appl.delete
( string name(.), long mode ) long appl.get.user
( string name(.), ref string user(12)) long appl.modify
( string name(.), long old.owner, long new.owner ) long appl.set
( string name(.), long mode )
Functions reference
1-2
Application locks
Syntax
long appl.delete( string name(.) )
Description
This removes a specified application lock. Only the owner of the lock can delete it. And a lock can be deleted only from within the same process in which it was set.
Return values
0
-1
-3 success; lock removed error; lock not found internal error
Context
3GL library function.
Syntax
long appl.get.user( string name(.), ref string user(12) )
Description
This retrieves the BAAN login name of the user who created the specified application lock.
Return values
0
-1 success lock not found
Context
3GL library function.
Functions reference
1-3
Application locks
Syntax
long appl.modify( string name(.), long old.owner, long new.owner )
Description
This changes the owner of a specified application lock. That is, it links the application lock to another 4GL process in the same bshell.
Arguments
name old.owner
The name of the application lock.
The process ID of the current owner.
new.owner
The process ID of the new owner.
Return values
0
-1
-2
-3 success lock not found
new.owner not found internal error
Context
3GL library function.
Syntax
long appl.set( string name(.), long mode )
Description
This creates an application lock for the current application.
Functions reference
1-4
Application locks
Arguments
name
The name of the application lock. This must be unique.
mode
The type of application lock to set:
APPL.READ
APPL.WRITE
APPL.EXCL
APPL.WIDE
You can combine APPL.WIDE with any one of the other lock types.
Return values
0
-1
-3
>0 success application-wide lock present internal error application lock already present; mode is returned
Context
3GL function library.
Examples
This example sets a write-type application lock for all companies. Only the owner can modify the application’s data in all companies.
appl.set("00112334455", APPL.WRITE + APPL.WIDE)
This example sets an exclusive-type application lock on a production order and subsequently deletes it.
if appl.set( "tisfc001" & tisfc001.pdno, APPL.EXCL ) <>0 then
| Lock is already present, give message return endif
. . . .
appl.delete( "tisfc001" & tisfc001.pdno )
Functions reference
1-5
Application locks
Functions reference
1-6
Use these functions to convert characters to their corresponding ASCII or multibyte codes, and vice versa.
long long asc chr$
( string characters )
( long code )
Syntax
long asc( string characters )
Description
This returns the code of a specified ASCII or multibyte character. If characters contains more than one character, asc() returns the sum of their codes.
Note
Multibyte characters with very high values can cause the returned long to overflow and loose its meaning. No check is made on the legality of the value.
Context
Bshell function.
Example
string select(10) asc_b = asc("B") | asc_b is set to 66 asc("abc") | Returns 294 (that is, 97 + 98+ 99) asc(select) | Returns the sum of the ASCII codes
| for each character in the string
| variable select
Functions reference
2-1
ASCII conversion
Syntax
string chr$( long code )
Description
This returns the ASCII or multibyte character that corresponds to the specified code. Note
Note
If code is greater than 255, the returned string is of type multibyte. No check is made on the legality of the value.
Context
Bshell function.
Example
chr$(65) | Returns "A" chr$(asc("A")) | Returns "A" chr$(27) | Returns the escape character
Functions reference
2-2
For each table associated with a particular company number, the audit server stores audit information in a set of sequence files. You use the audit functions and macros to access this information.
For each table in each company number, there is also an info file. This stores information about all sequence files for the table/company number combination, and control information for creating and maintaining the sequence files for that table/company number combination.
The following diagram illustrates the overall organization of the audit files for a particular company number.
Functions reference
3-1
Audit information
The following diagram illustrates the overall organization of the audit files for a particular table.
The audit server uses sequence files in rotation. When the last file is full, it starts writing to the first file again. So, if the current sequence file is 200, then sequence file 201 (if it exists) is the oldest sequence file and all sequence files
>200 are older than sequence files <= 200.
For full details of audit file structure and management, consult the BaanERP
Tools Technical Reference Manual.
The file ‘$BSE/lib/auditdefx.x’ specifies the path to BAAN audit files. All 4GL audit routines use this file to retrieve the path to the audit files.
You can override the default audit path by using the AUDIT_FILE_PATH environment variable.
For example, take the case where directory ‘/usr1/audit_data’ contains the audit data for modules ‘adv’ and ‘aad’ in the subdirectories ‘attadv’ and ‘attaad’.
These audit files can be referred to by setting:
AUDIT_FILE_PATH=/usr1/audit_data
Do not specify the final directory (‘attadv’ or ‘attaad’) in the audit path.
Functions reference
3-2
Audit information
If the host name is not included in the pathname, use aud_select_host() to select the required host.
Before reading information from an audit file, the audit server locks the relevant portion of the file. Other processes can read the information, but no process can write to the locked portion of the file while the read lock is in place. The read lock is released as soon as reading is completed.
Before updating an audit file, the audit server locks the relevant portion of the file with an exclusive type lock. This prevents other processes both reading and writing to the locked portion of the file. The exclusive lock is released as soon as the update is completed.
When the info header is read from the info file, only the info header part of the file is locked. When a sequence header is read from the info file, the sequence header, and the field specifying the header size, are locked.
When the header part of a sequence file is being updated, the sequence header in the sequence file, and the corresponding sequence header in the info file, are locked. In the sequence file, the table name, company number, and sequence header length fields are also locked.
#include <bic_audlib>
#include <bic_audhdr.h>
long aud_close_audit void aud_get_audit_dd void aud_get_col_info
( long seqid )
( const string seqhdr(), ref string colnames(,), ref long colinfo(,))
( const string seqhdr(), long col_no, ref string col_name(), ref long col_type, ref long col_dep, ref long col_len )
Functions reference
3-3
Audit information
long aud_get_fld_values long aud_get_hdr_size long aud_get_info_seq_ long long long long long long hdr_size aud_open_audit aud_read_audit_rec aud_read_info_hdr aud_read_info_seq_ hdr aud_read_next_ audit_rec aud_read_next_tran long aud_read_seq_hdr long aud_read_tran long aud_select_host long aud_update_ infofile long aud_write_info_hdr long aud_write_seq_hdr
( long colno, const long colinfo(,), const string rec_buff(), ref string values(,))
( long seqid )
( long seqid, long seqno )
( const string host_name(), const string table_name(), long compno, long seqno )
( long seqid, long rec_no, ref string rec_buff() )
( const string host_name(), const string table_name(), long compno, ref string info_hdr() )
( long seqid, long seqno, ref string seqhdr() )
( long seqid, ref string rec_buff() )
( long seqid, ref string tran_hdr() )
( long seqid, ref string seqhdr())
( long seqid, long tran_no, ref string tran_hdr() )
( const string table_name(), long compno, long user_interaction, ref string host_name() )
( long seqid, const string seqhdr)
( const string host_name(), const string table_name(), long compno, const string info_hdr )
( long seqid, const string seqhdr() )
Functions reference
3-4
Audit information
Syntax
long aud_close_audit( long seqid )
Description
Discards the specified sequence identifier. seqid is the identifier returned by
sequence file associated with an info file is closed, the info file is also closed.
Return values
0
-1 success error (for example, could not close the sequence file or info file).
Context
3GL library function.
Syntax
void aud_get_audit_dd( const string seqhdr(), ref string colnames(,), ref long colinfo(,) )
Description
This retrieves the audit data dictionary information from the sequence header of a particular sequence file.
Arguments
seqhdr
The buffer containing the sequence header. You fill this by calling
colnames
An array containing the names of the audited fields. This array must be allocated dynamically.
Functions reference
3-5
Audit information
colinfo
An array containing the data dictionary information for the audited fields. For example, the information for the first audited field can be interpreted as follows: colinfo(AUD_FLD_TYPE,1) the field type – for example,
DB.LONG, DB.FLOAT
colinfo(AUD_FLD_DEPT,1) the field depth – this is
always 1 for non-array fields colinfo(AUD_FLD_LEN,1) the field length
This array must be allocated dynamically.
Context
3GL library function.
Example
long audit_flds string colnames(1,1) based long colinfo(1,1) based audit_flds = aud_get_no_audit_flds(seqhdr) | get number of
| audited fields alloc.mem(colnames, AUD_COL_NAME_LEN, audit_flds) alloc.mem(colinfo, 3, aud_flds) aud_get_audit_dd( seqhdr, colnames, colinfo )
Syntax
void aud_get_col_info( const string seqhdr(), long col_no, ref string col_name(), ref long col_type, ref long col_dep, ref long col_len )
Description
This retrieves information about a specified field from the sequence header of a particular sequence file. It retrieves the same information as
Functions reference
3-6
Audit information
Arguments
seqhdr col_no
The buffer containing the sequence header. You fill this by calling
The column number.
colname
The field name.
coltype
The field type – for example, DB.LONG, DB.STRING.
col_dep col_len
The field depth. This is always 1 for non-array fields.
The field length.
Context
3GL library function.
Syntax
long aud_get_fld_values( long colno, const long colinfo(,), const string rec_buff(), ref string values(,) )
Description
This retrieves the values of a specified field from an audit record. You can use this for records of type insert, delete, and update only. For records of type insert and delete, you can retrieve the values of any field. For records of type update, you can retrieve the values of changed fields and primary key fields only.
Arguments
colno colinfo
The column number.
An array containing the audit DD of the sequence file that contains the audit record. You fill this by calling aud_get_audit_dd().
rec_buff
The buffer containing the audit record. You fill this by calling
Functions reference
3-7
Audit information
values
An array containing the field values in string format. There are two string elements, the first containing the old value of the field, the second containing the new value. For example: values(1,1) values(2,1) old value new value
The size of the both elements is determined by the predefined constant AUD_MAX_FLD_SIZE.
Return values
0
1
-1
Record of type insert or delete. In these cases, there is no new value.
Only values(1,1) is relevant.
Record of type update. Both old and new values are relevant.
Error. Possibly invalid column number or record not of type insert, delete, or update.
Context
3GL library function.
Example
| For a column of type DB.FLOAT
long colno, coltype, coldept string rec_buff(AUD_MAX_REC_SIZE) string values(AUD_MAX_FLD_SIZE,2) float new_value, old_value if ( aud_get_fld_values(colno, colinfo, rec_buff, values)
= 1 ) then new_value = load.float( values(1,1) ) old_value = load.float( values(2,1) ) endif
Functions reference
3-8
Audit information
Syntax
long aud_get_hdr_size( long seqid )
Description
Because the audit DD of a table can differ in different sequence files, the size of the sequence header can also differ from sequence file to sequence file.
This function returns the size (in bytes) of the header of a specified sequence file.
You can use the return value to allocate space for the sequence header before retrieving it with aud_read_info_seq_hdr() or aud_read_seq_hdr(). seqid is the sequence identifier returned by aud_open_audit() when the particular sequence file was opened.
Note
You can also use aud_get_info_seq_hdr_size() to retrieve the size of the sequence header. The value returned by both functions is normally the same.
Return values
>0
-1 sequence header size (in bytes) error; probably invalid seqid
Context
3GL library function.
Syntax
long aud_get_info_seq_hdr_size( long seqid, long seqno )
Description
Because the audit DD of a table can differ in different sequence files, the size of the sequence header can also differ from sequence file to sequence file.
This function returns the size (in bytes) of the header of a specified sequence file, as stored in the associated info file. You can use the return value to allocate space
Functions reference
3-9
Audit information
for the sequence header before retrieving it with aud_read_info_seq_hdr() or
Arguments
seqid
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqno
The sequence number of the sequence file.
Note
You can also use aud_get_hdr_size() to retrieve the size of the sequence header.
The value returned by both functions is normally the same.
Return values
>0
-1 length of the sequence file header error – possible reasons are:
– error occurred while opening sequence file
– open file limit reached
Context
3GL library function.
Syntax
long aud_open_audit( const string host_name(), const string table_name(), long compno, long seqno )
Description
This opens a specified sequence file. You identify the file to open by the table/company combination with which it is associated, the host on which it is located, and the sequence file number. The function returns a unique identifier for the file. Other audit functions use this identifier (referred to as the sequence identifier) to refer to this particular sequence file.
When you open a sequence file, the associated info file is automatically opened also (unless it is already open).
Functions reference
3-10
Audit information
Arguments
host_name
The name of the host on which the sequence file is to be accessed. You can use aud_select_host() to select the host to be used.
If this argument is an empty string, aud_select_host() is called automatically to select a host name.
table_name
The name of the table with which the sequence file is associated.
This takes the form ppmmfff, where pp is the package code,
mmm is the module code, and fff is the file number.
compno seqno
The company number.
The number of the particular sequence file to open.
Return values
>0
-1 sequence id for file error – possible reasons are:
– table or sequence file does not exist
– error occurred while opening sequence file
– open file limit reached
Context
3GL library function.
Syntax
long aud_read_audit_rec( long seqid, long rec_no, ref string rec_buff() )
Description
This retrieves a specified audit record from the current transaction. You can use
transaction. You can access information in the audit record using the transaction record macros (see “Macros (transaction record)”).
Functions reference
3-11
Audit information
Arguments
seqid rec_no
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
The number of the audit record within the transaction. Specify 1 to retrieve the first audit record, 2 to retrieve the second, and so on.
rec_buff
A buffer containing the actual audited record. The predefined constant AUD_MAX_REC_SIZE holds the size of this buffer.
Return values
0
-1 success error – possible reasons are:
– seqid does not exist
– rec_no does not exist
Context
3GL library function.
Syntax
long aud_read_info_hdr( const string host_name(), const string table_name(), long compno, ref string info_hdr() )
Description
This retrieves the header of the info file associated with a specified table and company number combination. You can access information in the info header using the info header macros (see “Macros (info header)”).
Arguments
host_name
The name of the host on which the info file is to be accessed.
You can use aud_select_host() to select the host to be used.
If this argument is an empty string, aud_select_host() is called automatically to select a host name.
Functions reference
3-12
Audit information
table_name
The name of the table with which the info file is associated. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
compno info_hdr
The company number.
The buffer in which the info header is stored. The info header size is fixed. The predefined constant AUD_INFO_HDR_SIZE holds the size of the buffer.
Return values
>0
-1 success error – possible reasons are:
– host not found
– info file not found
– error opening info file
– info file locked
– unable to unlock file after read action
– unable to close info file
Context
3GL library function.
Syntax
long aud_read_info_seq_hdr( long seqid, long seqno, ref string seqhdr() )
Description
This reads the header information for a particular sequence file from the associated info file. You can access information in the sequence header using the sequence header macros (see “Macros (sequence header)”).
Use aud_read_seq_hdr() to read the sequence header from the sequence file itself. The information retrieved by both functions is normally the same.
Functions reference
3-13
Audit information
Arguments
seqid seqno
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
The sequence number of the sequence file.
seqhdr
The buffer in which the sequence header information is stored. Use
size of this buffer.
Return values
0
-1 success error; probably invalid seqid
Context
3GL library function.
Syntax
long aud_read_next_audit_rec( long seqid, ref string rec_buff() )
Description
This reads the next audited record from the current transaction. You can use
access information in the audited record using the transaction record macros (see
“Macros (transaction record)”).
Arguments
seqid
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
rec_buff
A buffer containing the actual audited record. The predefined constant AUD_MAX_REC_SIZE holds the size of the buffer.
Functions reference
3-14
Audit information
Return values
0
-1 success error – possible reasons are: seqid does not exist or no more records in the current transaction of the specified sequence file
Context
3GL library function.
Syntax
long aud_read_next_tran( long seqid, ref string tran_hdr())
Description
This reads the next transaction header in the specified sequence file. You can use
can access information in the transaction header using the transaction header macros (see “Macros (transaction header)”).
Arguments
seqid
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
tran_hdr
A buffer containing the transaction header information. The predefined constant AUD_TRAN_HDR_SIZE holds the size of this buffer.
Return values
0
-1 success error – possible reasons are: seqid does not exist or no more transactions in the sequence file
Context
3GL library function.
Functions reference
3-15
Audit information
Syntax
long aud_read_seq_hdr( long seqid, ref string seqhdr() )
Description
This retrieves the header information from a specified sequence file. You can access information in the sequence header with the sequence header macros (see
“Macros (sequence header)” in Chapter 3, Audit information).
Use aud_read_info_seq_hdr() to read the sequence header from the info file instead of the sequence file. The information retrieved by both functions is normally the same.
Arguments
seqid
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqhdr
The buffer in which the sequence header information is stored. Use
size of this buffer.
Return values
0
-1 success error; probably invalid seqid
Context
3GL library function.
Syntax
long aud_read_tran( long seqid, long tran_no, ref string tran_hdr() )
Description
This reads a specified transaction header from a specified sequence file. You can use aud_read_tran() to read a specific transaction header and then use
Functions reference
3-16
Audit information
can access information in the transaction header with the transaction header macros (see “Macros (transaction header)” in Chapter 3, Audit information).
Arguments
seqid tran_no
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
The number of the required transaction within the sequence file.
Specify 1 to read the header for the first transaction in the file, specify 2 to read the header for the second transaction, and so on.
tran_hdr
A buffer containing the transaction header information. The predefined constant AUD_TRAN_HDR_SIZE holds the size of this buffer.
Return values
0
-1 success error – possible reasons are:
– sequence id does not exist
– transaction does not exist
Context
3GL library function.
Syntax
long aud_select_host( const string table_name(), long compno, long user_interaction, ref string host_name())
Description
Audit files can be located on more than one host (for example, on the local host and a remote host, or on two or more remote hosts). The system maintains a list of hosts where audit files for particular table and company number combinations are located. When accessing audit files, this host list is used to select the particular host on which the files are to be accessed.
files for a specified table and company are to be accessed. You can use this host
Functions reference
3-17
Audit information
name as input to aud_open_audit(), aud_read_info_hdr(), and
Arguments
table_name
The name of the table for which audit files are to be accessed. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
The company number.
compno user_interaction
Specifies whether or not user interaction is required. Possible values are:
USR_INTACTION_YES
If there is more than one host in the host list for the specified table and company number, the user is prompted to select the host to be used. The function then returns the name of that host. If there is only one host in the list, that host is returned automatically, without user interaction.
USR_INTACTION_NO
No user interaction. The 4GL library automatically selects the host. It returns the name of the first host in the host list.
If there is only one host in the list, it returns the name of that host.
host_name
This returns the name of the selected host.
Notes
If the AUD_HOST_NAME environment variable is set, aud_select_host() always returns the host name stored in this variable, regardless of the
user_interaction setting specified by the function. For example, the application will use the audit file on the remote host ‘ed5c21’, if the environment variable has been set as follows:
AUD_HOST_NAME=ed5c21
Note that this environment variable applies to all tables. If it is set, it is used for accessing the audit files of all tables.
Functions reference
3-18
Audit information
Return values
>=0 success
-1 error; possibly unable to find host list or auditing not enabled for the specified table and company
Context
3GL library function.
Syntax
long aud_update_infofile( long seqid, const string seqhdr )
Description
This writes sequence header information to the info file associated with the specified sequence file. You can set the information for the sequence header with the sequence header macros (see “Macros (sequence header)” in Chapter 3, Audit information).
Note that the sequence header information is not automatically copied to the sequence header in the sequence file itself. To ensure that there is no mismatch between the sequence headers in the info file and in the sequence file, use
Arguments
seqid
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqhdr
The buffer that contains the sequence header information.
Return values
0
-1 success error – possible values are:
– error occurred while opening the information file
– open file limit reached
– incorrect sequence identifier
Functions reference
3-19
Audit information
Context
3GL library function.
Syntax
long aud_write_info_hdr( const string host_name(), const string table_name(), long compno, const string info_hdr )
Description
This writes info header information to a specified info file. You can set the information for the info header with the info header macros (see “Macros (info header)” in Chapter 3, Audit information).
Arguments
host_name
The name of the host on which the info file is to be accessed. You can use aud_select_host() to select the host to be used.
If this argument is an empty string, aud_select_host() is called automatically to select a host name.
table_name
The name of the table with which the info file is associated. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
compno info_hdr
The company number.
The buffer that contains the header information to be written to the info file.
Return values
>0
-1 success error – possible reasons are:
– host not found
– table or information file does not exist
– error occurred while opening information file
– open file limit reached
Functions reference
3-20
Audit information
Context
3GL library function.
Syntax
long aud_write_seq_hdr( long seqid, const string seqhdr() )
Description
This writes header information to a specified sequence file. You can set the information for the sequence header with the sequence header macros (see
“Macros (sequence header)” in Chapter 3, Audit information).
The function writes the header information to the sequence file and to the associated info file.
Arguments
seqid
The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqhdr
The buffer that contains the header information to be written to the sequence file.
Return values
0
-1 success error; probably incorrect seqid
Context
3GL library function.
Functions reference
3-21
Audit information
Use these macros for mapping info header information. The ‘get’ macros take
info_hdr as their input. This is filled by calling aud_read_info_hdr(). The 'set' macros update the info_hdr buffer. Use aud_write_info_hdr() to update the information file header itself.
aud_get_version()
string aud_get_version( string info_hdr() )
This returns the current version of the info file and related sequence files.
aud_get_ tablename()
string aud_get_tablename( string info_hdr())
This returns the name of the table to which the specified info file relates.
aud_get_compno()
long aud_get_compno( string info_hdr() )
This returns the company number of the table to which the info file relates.
aud_get_status()
long aud_get_status( string info_hdr() )
This returns the value of the status field in the info header.
The status field indicates whether the sequence file reuse feature is enabled or disabled.
aud_get_from_ seqno()
long aud_get_from_seqno( string info_hdr() )
This returns the starting number for sequence files related to the info file.
aud_get_to_seqno()
long aud_get_to_seqno( string info_hdr() )
This returns the maximum sequence number for sequence files related to the info file.
aud_get_curr_ seqno()
long aud_get_curr_seqno( string info_hdr() )
This returns the sequence number of the current sequence file. This is the sequence file to which new audit information will be written.
Functions reference
3-22
Audit information aud_get_curr_ security()
long aud_get_curr_security( string info_hdr() )
This returns the security permissions for the info file and associated sequence files. The return value can be a combination of the following values:
AUD_SECU_NONE
AUD_SECU_ALL
AUD_SECU_PRINT
AUD_SECU_CLEAN no permissions all permissions print permissions purge permissions
AUD_SECU_MAINTAIN maintain permissions
AUD_SECU_APPL_DEF application-defined permissions
For example: long security security = aud_get_curr_security( info_hdr ) if (bit.and (security, AUD_SECU_NONE)) then
| No permissions on info file else if (bit.and (security, AUD_SECU_ALL)) then
| All permissions on info file else if (bit.and (security, AUD_SECU_PRINT)) then
| Print permissions on info file endif if (bit.and (security, AUD_SECU_CLEAN)) then
| Purge permissions on info file endif if (bit.and (security, AUD_SECU_MAINTAIN)) then
| Maintain permissions on info file endif then if (bit.and (security, AUD_SECU_APPL_DEF))
| Application-defined permissions on file endif endif endif
Functions reference
3-23
Audit information aud_get_max_ audit_file_size() aud_set_status()
long aud_get_max_audit_file_size( string info_hdr() )
This returns the maximum size (in bytes) of sequence files related to the info file.
void aud_set_status( long status, string info_hdr() )
This stores the value of status in the status field of the info header.
aud_set_to_seqno()
void aud_set_to_seqno( long to_seq, string info_hdr() )
This stores the value of to_seq in the maximum sequence number field of the info header.
aud_set_curr_ seqno() aud_set_max_ audit_file_size()
void aud_set_curr_seqno( long c_seq, string info_hdr() )
This stores the value of the c_seq in the current sequence number field of the info header.
void aud_set_max_audit_file_size( long m_size, string info_hdr() )
This stores the value of m_size in the maximum file size field of the info header.
aud_set_security()
void aud_set_security( long c_sec, string info_hdr() )
This stores the value of c_sec in the security field of the info header. For a list of valid values, see
Use these macros for mapping sequence header information. The ‘get’ macros take seq_hdr as their input. This is filled by calling aud_read_seq_hdr() or
itself in the sequence file and info file respectively.
Dates are returned as UTC in the form YYYYMMDD. Times are returned as
UTC in the form HHMMSS.
Functions reference
3-24
Audit information aud_get_app_info1() to aud_get_app_info4()
void aud_get_app_info1( string seq_hdr(), string app1(4) ) void aud_get_app_info2( string seq_hdr(), string app2(4) ) void aud_get_app_info3( string seq_hdr(), string app3(4) ) void aud_get_app_info4( string seq_hdr(), string app4(4) )
These fill their second argument with the applicationspecific information from the sequence header.
string aud_get_creat_date( string seq_hdr())
This returns the creation date (in UTC) of the sequence file. Use utc.to.local() to convert the UTC date to a local date.
string aud_get_creat_time( string seq_hdr())
This returns the creation time (in UTC) of the sequence file. Use utc.to.local() to convert the UTC time to local time.
long aud_get_no_audit_flds( string seq_hdr())
This returns the number of audited fields in the sequence file.
long aud_get_no_prim_flds( string seq_hdr())
This returns the number of primary key fields among the audited fields in the sequence file.
long aud_get_no_trans( string seq_hdr() )
This returns the number of transactions in the sequence file.
long aud_get_seqno( string seq_hdr() )
This returns the sequence number of the sequence file.
Functions reference
3-25
Audit information
long aud_get_seq_status( string seq_hdr() )
This returns a value indicating the termination status of the sequence file. Possible values are:
AUD_TERM_MAX_SIZE file terminated because it reached its maximum size
AUD_TERM_DD_CHGD file terminated because table definitions in data have been changed
AUD_TERM_USER_FRCD file forcibly terminated by user
AUD_TERM_CORRUPT file terminated because of mismatch between sequence headers in info file and sequence file
AUD_SEQ_REMOVED sequence file removed using session "ttaad4161m000"
(Purge Audit Files)
AUD_TERMINATE_VERSION file terminated because a new audit server has been activated
Any of the above values can be bitwise anded with predefined constants to determine the reason for termination of a particular sequence file.
For example: long term_status term_status = aud_get_seq_status(seq_hdr) if ( bit.and (term_status,AUD_TERM_MAX_SIZE) ) then
| Termination because of reaching max size.
endif if ( bit.and (term_status,AUD_TERM_DD_CHGD) ) then
| Termination because of dd change.
endif if ( bit.and (term_status,AUD_TERM_USER_FRCD) ) then
| Termination forced by user.
endif
Functions reference
3-26
Audit information
long aud_get_seq_full_status( string seq_hdr() )
This returns the value of the status field in the sequence header. Note that you cannot use this value because the version information is included in the status. Use
long aud_get_seq_version( string seq_hdr())
This returns the version of the sequence file as stored in the sequence header.
string aud_get_term_date( string seq_hdr())
This returns the termination date (in UTC) of the sequence file (if the file is terminated). Use
string aud_get_term_time( string seq_hdr())
This returns the termination time (in UTC) of the sequence file (if the file is terminated). Use
void aud_ set_app_info1( string app1(4), string seq_hdr() ) void aud_set_app_info2( string app2(4), string seq_hdr() ) void aud_set_app_info3( string app3(4), string seq_hdr() ) void aud_set_app_info4( string app4(4), string seq_hdr() )
These write application-specific information to
seq_hdr.
void aud_set_term_date( string t_date(), string seq_hdr())
This stores the content of t_date in the termination date field of the sequence header.
void aud_set_term_time( string t_time(), string seq_hdr())
This stores the content t_time in the termination time field of the sequence header.
Functions reference
3-27
Audit information
void aud_set_seq_status( long st, string seq_hdr() )
This stores the content of st in the status field of the sequence header.
Use these macros for mapping transaction header information. All the macros take tran_hdr as their input. This is filled by calling aud_read_tran() or
long aud_get_tran_bytes( string tran_hdr() )
This returns the total size in bytes of the transaction data.
string aud_get_tran_commit_date( string tran_hdr() )
This returns the UTC commit date from the transaction header.
string aud_get_tran_commit_time( string tran_hdr() )
This returns the UTC commit time from the transaction header.
long aud_get_tran_entries( string tran_hdr())
This returns the number of audited actions in the transaction.
long aud_get_tran_id( string tran_hdr(), long g1, long g2)
This reads the transaction id from the transaction header. The transaction id consists of two longs which together form a unique identification.
string aud_get_tran_sess( string tran_hdr() )
This returns the name of the session that committed the transaction.
Functions reference
3-28
Audit information
long aud_get_tran_status( string tran_hdr() )
This returns the commit status of the transaction.
Possible values are:
AUD_COMMITTED transaction committed
AUD_ABORTED transaction canceled
AUD_PREPARED it is not certain whether the
transaction has been committed
or aborted
string aud_get_tran_tuname(string tran_hdr())
This returns the BAAN user name of the user who performed the transaction.
long aud_get_tran_uuid( string tran_hdr())
This returns the UNIX user id of the user who performed the transaction.
Use these macros for mapping transaction records. All the macros take rec_buff as their input. This is filled by calling aud_read_audit_rec() or
void aud_get_rec_app_info( string appinfo(4), string rec_buff() )
This reads the application-specific information of the record into appinfo.
string aud_get_rec_op_type( string rec_buff() )
This returns the type of action of the record. Possible values are:
"I" insert record
"D" delete record
"U" update record
"L" clear table
"R" drop table
"C" create table
Functions reference
3-29
Audit information
long aud_get_rec_seqno( string rec_buff() )
This retrieves the sequence number of the record within the transaction.
Use these macros to retrieve transaction dates and times. All the macros take
tran_hdr as their input. This is filled by calling aud_read_tran() or
long aud_get_tran_date_yyyy( string tran_hdr() )
This retrieves the year value from transaction commit date. The year is represented by four digits.
long aud_get_tran_date_mm( string tran_hdr() )
This retrieves the month value from the transaction commit date.
long aud_get_tran_date_dd( string tran_hdr() )
This retrieves the day value from the transaction commit date.
long aud_get_tran_time_hh( string tran_hdr() )
This retrieves the hours value from the transaction commit time.
long aud_get_tran_time_mm( string tran_hdr() )
This retrieves the minutes value from the transaction commit time.
long aud_get_tran_time_ss( string tran_hdr() )
This retrieves the seconds value from the transaction commit time.
Functions reference
3-30
Audit information
The input to these macros is a date string in the form YYYYMMDD or a time string in the form HHMMSS.
long aud_get_date_yyyy( string s_dat() )
This retrieves the year value from the date string s_dat.
The year is represented by four digits.
long aud_get_date_mm( string s_dat() )
This retrieves the month value from the date string s_dat.
long aud_get_date_dd( string s_dat() )
This retrieves the day value from the date string s_dat.
long aud_get_time_hh( string s_tim() )
This retrieves the hours value from the time string s_tim.
long aud_get_time_mm( string s_tim() )
This retrieves the minutes value from the time string
s_tim.
Functions reference
3-31
Audit information
This sample program illustrates the general sequence of reading audit records in a sequence file and displaying audit field information. It also shows how to write application information to a sequence header.
Assume that the table has the following DD:
Field 1 : integer (2 bytes)
Field 2 : float (4 bytes)
#include <bic_audlib>
#include <bic_audhdr.h> long seqid long seq_hdr_size string seq_hdr(1) based string colnames(1,1) based long colinfo(1,1) based string tran_hdr(AUD_TRAN_HDR_SIZE) string rec_buff(AUD_MAX_REC_SIZE) long no_recs long no_trans long audit_flds string appinfo(4) string values(AUD_MAX_FLD_SIZE,2) long type
| open a seqid to table aabdb000, company 0,
| sequence file 0 seqid = aud_open_audit( "", "aabdb000", 0, 0 ) if ( seqid = -1 ) then error endif
| get the size of the sequence file header seq_hdr_size = aud_get_hdr_size( seqid ) alloc.mem( seq_hdr, seq_hdr_size )
| read the sequence file header if ( aud_read_seq_hdr( seqid, seq_hdr ) = -1 ) then error endif audit_flds = aud_get_no_audit_flds( seq_hdr ) no_trans = aud_get_no_trans( seq_hdr )
Functions reference
3-32
Audit information
| write 16 bytes of application-specific information
| to seqhdr appinfo(1) = "aaaa" aud_set_app_info1(appinfo, seqhdr) appinfo(1) = "aaaa" aud_set_app_info2(appinfo, seqhdr) appinfo(1) = "aaaa" aud_set_app_info3(appinfo, seqhdr) appinfo(1) = "aaaa" aud_set_app_info4(appinfo, seqhdr) alloc.mem( colnames, AUD_COL_NAME_LEN, audit_flds ) alloc.mem( colinfo, 3, audit_flds ) aud_get_audit_dd( seq_hdr, colnames, colinfo ) for i = 1 to no_trans if ( aud_read_tran(seqid, i, tran_hdr) = -1 ) then endif error
| get number of records no_recs = aud_get_tran_entries(tran_hdr) for j = 1 to no_recs
| read audit records if (aud_read_audit_rec(seqid,j,rec_buff) = -1) then error endif for k = 1 to audit_flds ind = aud_get_fld_values(k, colinfo, rec_buff, values) if ( ind = 1 ) then
| both new and old values exist type = colinfo(1,k) print_value(type, values(1,1))
| prints old value print_value(type, values(2,1))
| prints new value endif if ( ind = 0 ) then
| only one value exists type = colinfo(1,k) print_value(type, values(1,1))
| prints unchanged value endif endfor endfor endfor
Functions reference
3-33
Audit information
| write sequence header if ( aud_write_seq_hdr(seqid, seq_hdr) = -1 ) then error endif
| close seqid if ( aud_close_audit(seqid) = -1 ) then error endif
| Function to format and print the values print_value( long type, const string values() )
{ float fval long sval on case type
DB.FLOAT: fval = load.float( values(1) )
| print fval
DB.INTEGER: sval = load.short( values(1) )
| print sval
...
endcase
}
Functions reference
3-34
Use these functions to compute binary bit operations on bit patterns. The bit patterns can be of type long or they can be hexadecimal constants. When using hexadecimal constants, these must begin with ’0x’.
long bit.and
long bit.exor
long bit.in
long bit.inv
long bit.or
long bit.shiftl
long bit.shiftr
( long pattern1, long pattern2 )
( long pattern1, long pattern2 )
( long pattern1, long pattern2 )
( long pattern1 )
( long pattern1, long pattern2 )
( long bitpattern, long no_of_bits )
( long bitpattern, long no_of_bits )
Syntax
long bit.and( long pattern1, long pattern2 ) long bit.exor( long pattern1, long pattern2 ) long bit.in( long pattern1, long pattern2 ) long bit.inv( long pattern1 ) long bit.or( long pattern1, long pattern2 )
Description
These functions compute binary bit operations on one or two bit patterns. Both patterns must be of type long; a long is 32 bits.
Return value
The return value is the result of the operation. It is always a long value.
Functions reference
4-1
Bit operations
Examples
The following examples illustrate how these functions work.
Function
Computation and result
long bit.and(5, 6)
0101
0110
0100 long bit.exor(5, 6)
0101
0110
0011 long bit.or(5, 6)
0101
0110
0111
Function
Computation and result
long bit.inv(6)
0110
1001 long bit.in(5, 6)
0101
0110
FALSE (0) long bit.in(4, 6)
0100
0110
TRUE (<>0)
You can specify hexadecimal constants as parameters instead of bit patterns.
These constants must start with ’0x’. The following example illustrates this.
Function
result = bit.and( 0x01b8, 0x2cdf )
Computation and result
00000000000110111000
00100000110011011111
00000000000010011000
(hexadecimal 0x00098;
decimal 152)
Notes
You can also use the mathematical operators +, -, and / for computing bit operations. The operands must be declared as variables of type SET. You can declare such a variable only with a domain declaration where the domain is of database type SET.
n
The operator + equates to the function bit.or().
n
The operator * equates to the function bit.and().
n
The operator / equates to the function bit.exor().
n
The operator - equates to a special form of the function bit.and(). That is, ab
for sets equates to bit.and(a, bit.inv(b))
for longs. If the SET variables are represented as longs, the following example explains the operator:
0101
0110
0001
Functions reference
4-2
Bit operations
n
When using SET constants as operands, the keyword IN equates to the function bit.in(). The following example illustrates the use of bit operations on SET constants. Note that EMPTY is a keyword for the empty set; all bits are zero (set value 0).
domain cf a,b | domain declaration: cf, a, and b
| are of type SET
| see also the function cf$()
a = empty | clear a
a = cf.dim | set a to dim
a = a + cf.reverse | add/enable reverse
a = a - cf.dim | delete/disable dim
a = a / cf.underline | toggle underline
a in b
if ( a in b ) then
message( "All elements of a are in b" )
endif
if ( cf.reverse * a ) then
message( "a contains reverse" )
endif
if ( a ) then
message( "a contains at least one argument" )
endif
if ( a=empty ) then
message( "a is an empty set" )
endif
The following diagrams illustrate how set operations work (a and b are sets):
Context
Bshell functions.
Functions reference
4-3
Bit operations
Syntax
long bit.shiftl( long bitpattern, long no_of_bits ) long bit.shiftr( long bitpattern, long no_of_bits )
Description
These shift a bit pattern to the left or to the right. The bit pattern can be of type long, or it can be a hexadecimal constant. When using a hexadecimal constant, it must begin with ’0x’. The no_of_bits argument indicates the number of bits that the pattern must be shifted.
Return value
The result of the shift operation as a decimal value.
Context
Bshell functions.
Example
long result result = bit.shiftr( 0x63f, 2 )
Functions reference
4-4
The Business Chart Manager is a tool that displays data graphically, in charts.
The Business Chart Manager supports a variety of chart types, including, pie, line, symbol, high-low, and layer. The input can consist of data from a database, a file, or some other appropriate source.
In this document, the term graph refers to a chart drawn within a coordinate system with two or more axes. The term pie refers to a circular chart, divided into segments, which illustrates the quantitative relationship between different groups of data.
Example
This example illustrates how the Business Chart Manager builds a chart.
Source data
The following figures represent the quantity of goods sold per month by three different companies.
Jan
Feb
Mar
. . .
Dec
Company 1
40
20
20
. . .
30
Company 2
30
25
40
. . .
35
Company 3
10
15
10
. . .
20
The Business Chart Manager organizes this data into twelve categories (one for each month) and three series (one for each company). The data value for a particular data category and data series can be represented as a data point in a chart.
Functions reference
5-1
Business Chart Manager
Axis-oriented graph
The sample data illustrated above can be plotted on a single axis-oriented graph.
In the Business Chart Manager, a graph can has up to four axes, as follows: category axis – x-axis data axis – y-axis series axis – z-axis data axis II – second y-axis
The x-axis represents the data categories (in this case, the months) against which each data value is plotted. The y-axis represents the value scale against which each data value is plotted. The values for each data series (in this case, the different companies), are differentiated in a variety of ways, depending on the chart type used. In a line graph, a line joins the data values for a particular series.
The various series can be differentiated by using different line types and/or colors. On a bar graph, a vertical or horizontal bar represents each data value.
Bars representing the same series have the same color, pattern, and width.
The data axis II is used in combination with data axis I when two (or more) different series must be drawn on different scales in order to facilitate comparison.
Pie Chart
A pie chart can represent only a single data series. The sample data illustrated above can be represented by either twelve or three pie charts, depending on whether the data is sorted by category or series:
Sorted by category Each pie chart illustrates the relationship between the different series (that is, the companies) for one category.
This results in twelve pie charts, one for each category
(that is, month).
Each diagram has three segments, representing the three data series. The size of each segment is proportional to the value of the data point in relation to the total in the category (month).
This option facilitates comparison of the three companies for each month.
Functions reference
5-2
Business Chart Manager
Sorted by series Each pie chart illustrates the different category values within one series (that is, a company). This results in three pie charts, one for each company.
Each diagram has twelve segments, representing the twelve categories. The size of the segments depends on the data value of each category as a percentage of the total of all data values in the series.
The window preferences, fonts, charts, chart types, and option sets for a particular Chart Manager session are defined in a Chart Manager application.
When you start the Chart Manager from a program script, you specify the particular Chart Manager application you want to use.
To create a Chart Manager application, use the following steps.
1
Start the Chart Manager Application Data session (ttchm1500m000)).
2
Create a new application record.
3
Define the option sets (Chart-Specific Options).
4
Create a default window setting (Window Preferences).
5
Start the Chart Manager from the Chart Manager Application Data session
(ttchm1500m000).
6
Create the chart types required to present the data.
By using the Business Chart Manager functions described in this document, you can create a client application that starts the Business Chart Manager and that sends data to and receives data from the Business Chart Manager. For further details on using the Chart Manager, see the session help.
The Business Chart Manager functions fall into three groups:
Input functions These send data from the application to the Chart Manager.
The function names in this group end in .in
Functions reference
5-3
Business Chart Manager
Output functions These functions send data from the Chart Manager to the application. The function names in this group end in .out.
Within this group, there is a further subdivision: n
Functions with the extension .first retrieve the first value for a particular object from the Chart Manager.
Other functions n
Functions with the extension .next retrieve the next value for a particular object from the Chart Manager. Before you can call a .next function, you must already have retrieved the first value by calling the relevant .first
function.
Miscellaneous functions. For example, control functions or functions to start and end the Business Chart Manager.
long chm.axis.in
long long long long chm.axis.out
chm.chartman
chm.check
chm.data.in
long chm.data2domain.
in long chm.delete.data
long chm.delete.
data2domains
( )
( )
( long axis_name, long logarithmic, long log_base, long divisions, double divisionstep, double intersection, string division_set(16) )
( long axis_name, ref long logarithmic, ref long log_base, ref long divisions, ref double divisionstep, ref double intersection, ref string division_set() )
( string chart_manager(80), string title(80), string user(14), string owner(14) [, string version(4), string release(2), string cust(4)])
( string chart_manager(14), string user(14), string chart_type(16) )
( double series_value, double category_value, long data_number, double data_value, long footnote_no, [ long duplicate_option ] )
( double series_value )
Functions reference
5-4
Business Chart Manager
long chm.delete.
footnotes long chm.delete.
projections long chm.delete.sets
long chm.disconnect
long chm.domain.in
long chm.domain.out
long chm.draw
long chm.first.data.
out long chm.first.
long chm.first.
long chm.first.
long chm.first.set.
long long long data2domain.out
footnote.out
projection.out
out chm.footnote.in
chm.get.request
chm.new
( )
( )
( )
( )
( long domain_name, long data_type, string set_name(16), string title(16), string unit_label(16), double from_value, double to_value, double interval, string display_format(80 )
( long domain_name, ref long data_type, ref string set_name(), ref string title(), ref string unit_label(), ref double from_value, ref double to_value, ref double interval, ref string display_format())
( [ double cat_from_value ] )
( long option, ref double series_value, ref double category_value, ref long data_number, ref double data_value, ref long footnote_no )
( ref double series_value )
( ref long footnote_no, ref string footnote_text() )
( ref double projection_point, ref long footnote_no )
( string set_name(16), ref long element_number, ref string element_name() )
( long footnote_no, string footnote_text(80) )
( ref long chart_no, ref double category_from_value, ref double category_to_value )
( string chart_name(16), ref string chart_type() )
Functions reference
5-5
Business Chart Manager
long chm.next.data.
out long chm.next.
data2domain.out
long chm.next.
footnote.out
long chm.next.
projection.out
( long option, ref double series_value, ref double category_value, ref long data_number, ref double data_value, ref long footnote_no )
( ref double series_value )
( ref long footnote_no, ref string footnote_text() )
( ref double projection_point, ref long footnote_no ) long chm.next.set.out
( string set_name(16), ref long element_number, ref string element_name() ) long chm.open
long chm.projection.
in long chm.remove
void chm.scale.axis
( string chart_name(16) )
( double projection_point, long footnote_no )
( string chart_manager(80), string owner_from(14), string owner_to(14) )
( double from_value, double to_value, long divisions, double factor, ref double domain_from_value, ref double domain_to_value, ref double divisionstep ) long chm.select
long long long long long chm.set.in
chm.set.option
chm.set.timer
chm.title.in
chm.title.out
( string chart_manager(80), string title(80), long mode, string user(14), string owner(14), ref string chart_name(16), ref string chart_type(16) )
( string set_name(16), ref long element_number, string element_name(80) )
( long option, long flag )
( long time )
( string main_title(80), string sub_title(80) )
( ref string main_title(), ref string sub_title() )
Functions reference
5-6
Business Chart Manager
Syntax
long chm.axis.in( long axis_name, long logarithmic, long log_base, long divisions, double divisionstep, double intersection, string division_set(16) )
Description
This defines an axis for an axis-oriented graph.
Arguments
axis_name
This specifies which axis is being defined. Possible values are:
CHM_SERIES_AXIS
CHM_CATEGORY_AXIS
CHM_DATA_AXIS
CHM_DATA2_AXIS
logarithmic
If logarithmic scaling is required, set this to true. For linear scaling, set it to false.
log_base
For logarithmic scaling, this indicates the log base that must be used. The argument is ignored if logarithmic is set to false.
divisions
This specifies the number of divisions into which the axis must be divided. The domain definition determines the start and end values for the axis. The Business Chart Manager calculates the scaling on the basis of the number of divisions specified here and the interval between divisions, as specified by divisionstep.
If either divisions or divisionstep is set to 0, the Business Chart
Manager calculates both arguments itself.
divisionstep
This specifies the interval between two divisions on the axis.
You can use chm.scale.axis() to calculate the division step.
intersection
This indicates the value on the data axis where the category and data axes intersect.
division_set
Normally, the values or labels from the associated domain are displayed on the axis. You can override this by specifying the name of a different set here. You create the set with
Functions reference
5-7
Business Chart Manager
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.axis.out( long axis_name, ref long logarithmic, ref long log_base, ref long divisions, ref double divisionstep, ref double intersection, ref string division_set() )
Description
This retrieves information about a specified axis from the Business Chart
Manager. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Arguments
axis_name
This specifies the axis about which you want to retrieve information. The possible values are:
CHM_SERIES_AXIS
CHM_CATEGORY_AXIS
CHM_DATA_AXIS
CHM_DATA2_AXIS
logarithmic
This returns true if the axis uses logarithmic scaling, or false if it uses linear scaling.
log_base divisions
If logarithmic returns true, this argument returns the log base used.
This returns the number of divisions into which the axis is divided.
divisionstep
This returns the interval between two divisions on the axis.
Functions reference
5-8
Business Chart Manager
intersection
This returns the value on the data axis where the category and data axes intersect.
division_set
If the labels or values displayed on the axis are provided by a set created by chm.set.in() instead of by the domain associated with the axis, this argument returns the name of the set used.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.chartman( string chart_manager(80), string title(80), string user(14), string owner(14), [, string version(4), string release(2), string cust(4)])
Description
This starts the Business Chart Manager for a specified Business Chart Manager application, user, owner, and, optionally, VRC code.
Window preferences, fonts, charts, chart types, and option sets are defined by
Business Chart Manager application. For a particular application, authorizations, option sets, and window preferences are defined by user (see the Chart Manager
Application Data session (ttchm1500m000)). You can also assign the same option set to a group of users. The owner is the creator of the charts; the charts are stored under the owner name (for example, a login name). Users can change only those charts they have created themselves.
Functions reference
5-9
Business Chart Manager
Arguments
chart_manager
This specifies the name of a Business Chart Manager application. This corresponds to a particular record in the
Chart Manager application data session (ttchm1500m000).
The name takes the following format: pp package code mmm module code xxx the name of the application
title
This specifies the window title.
user owner version, release, cust
This specifies the name of the relevant user.
This specifies the name of the relevant owner.
It is possible to assign a VRC code to a chart. These optional arguments specify the relevant VRC codes.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.check( string chart_manager(14), string user(14), string chart_type(16) )
Description
This checks whether a specified user can access a particular chart type within a specified Business Chart Manager application.
Functions reference
5-10
Business Chart Manager
Arguments
chart_manager
This specifies the name of a Business Chart Manager application. This corresponds to a particular record in the
Chart Manager application data session (ttchm1500m000).
The name takes the following format: pp package code mmm module code xxx the name of the application
user
The user name.
chart_type
The chart type.
Return values
true false the user can select the specified chart type the user cannot select the specified chart type
Context
3GL library function.
Syntax
long chm.data.in( double series_value, double category_value, long data_number, double data_value, long footnote_no, [ long duplicate_option ] )
Description
This sends a data point to the Business Chart Manager. You must call this function for each data point that you want to send.
Arguments
series_value
This specifies the series to which the data point belongs.
category_value
This specifies the category to which the data point belongs.
Functions reference
5-11
Business Chart Manager
data_number data_value footnote_no duplicate_ option
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
If there is more than one data point per category (a high-low graph, for example), this indicates the sequence number of the data point within the category. If there is only one data point per category, the sequence number is 1.
The data value for the specified series and category. The data value must lie within the scope of the data domain.
If you want to include a footnote for the data point, specify the number of the footnote here. Use chm.footnote.in() to create the footnote.
If the new data value has the same series_value,
category_value and data_number as another data value, use this optional argument to indicate the action that must be taken. The possible values are:
CHM_OVERWRITEDUPL overwrite the existing data value
CHM_IGNOREDUPL ignore this data value
CHM_INSERTDUPL
CHM_ADDDUPL
increase data_value by 1
double the value of data_value
Syntax
long chm.data2domain.in( double series_value )
Description
Data domain II defines the start value, end value, and step size for the data II axis. You use the second data domain and axis when you want to draw two different series to different scales in order to facilitate comparison. You use
series uses the second data domain. By default, the other series uses the normal data domain.
Functions reference
5-12
Business Chart Manager
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.delete.data()
Description
This removes from memory the data points added by chm.data.in(). The function cannot delete data points that the application has already saved.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.delete.data2domains()
Description
This removes the second data domain from memory. The series that uses the second data domain will use the first data domain after this function has been called.
Return values
CHM_OK success
CHM_ERROR error
Functions reference
5-13
Business Chart Manager
Context
3GL library function.
Syntax
long chm.delete.footnotes()
Description
This removes from memory the footnotes added by chm.footnote.in(). The function cannot delete values that the application has already saved.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.delete.projections()
Description
This removes from memory the projection points added by chm.projection.in().
The function cannot delete values that the application has already saved.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-14
Business Chart Manager
Syntax
long chm.delete.sets()
Description
This removes from memory the set elements added by chm.set.in(). The function cannot delete values that the application has already saved.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.disconnect()
Description
This disconnects the Business Chart Manager from the application, enabling independent user interaction. The user can now work with the Chart Manager and modify data, without affecting the data in the application.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-15
Business Chart Manager
Syntax
long chm.domain.in( long domain_name, long data_type, string set_name(16), string title(16), string unit_label(16), double from_value, double to_value, double interval, string display_format(80) )
Description
This defines a domain, which specifies a start value, an end value, and a step value for a particular axis. The domain determines which values are legal for the axis.
Arguments
domain_name
This specifies the name of the domain. The possible values are:
CHM_SERIES_DOMAIN
CHM_CATEGORY_DOMAIN
CHM_DATA_DOMAIN
CHM_DATA2_DOMAIN
data_type
This specifies the domain type. The possible values are: n n n
CHM_REAL real (domain consists of integers and fractions)
CHM_INTEGER integer (domain consists of integers)
CHM_SET enumerated set (domain consists of a set of labels)
set_name(16)
When the domain type is CHM_SET, this specifies the name of the relevant set. For other domain types, specify an empty string [""] here. Use chm.set.in() to define the set.
title, unit_label from_value, to_value interval display_ format
These specify the axis title and the unit of measurement that must be displayed in the chart to describe the axis.
These specify the start and end values of the domain. You can calculate these values with the function chm.scale.axis().
This specifies the interval between domain values.
For domains of type CHM_REAL or CHM_INTEGER, you must specify a display format. See edit().
Functions reference
5-16
Business Chart Manager
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.domain.out( long domain_name, ref long data_type, ref string set_name(), ref string title(), ref string unit_label(), ref double from_value, ref double to_value, ref double interval, ref string display_format() )
Description
This retrieves information from the Business Chart Manager about a specified domain. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Arguments
domain_name data_type
This specifies the name of the domain for which you want to retrieve information. The possible values are:
CHM_SERIES_DOMAIN
CHM_CATEGORY_DOMAIN
CHM_DATA_DOMAIN
CHM_DATA2_DOMAIN
This returns the domain type. The possible values are: n n n
CHM_REAL real (the domain consists of integers and fractions)
CHM_INTEGER integer (the domain consists of integers)
CHM_SET enumerated set (the domain consists of a set of labels)
Functions reference
5-17
Business Chart Manager
set_name(16)
When the domain type is CHM_SET, this returns the name of the relevant set. For other domain types, this returns an empty string [""] here.
title, unit_label from_value, to_value interval
These return the axis title and the unit of measurement that are displayed in the chart to describe the corresponding axis.
These return the start and end values of the domain.
This returns the interval between domain values.
display_format
For domains of type CHM_REAL or CHM_INTEGER, this returns the display format. See edit().
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.draw( [ double cat_from_value ] )
Description
This signals to the Business Chart Manager that it must start (re)drawing the chart. The optional argument enables you to specify the value of the first category for which the chart must be (re)drawn.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-18
Business Chart Manager
Syntax
long chm.first.data.out( long option, ref double series_value, ref double category_value, ref long data_number, ref double data_value, ref long footnote_no )
Description
This retrieves information from the Business Chart Manager about the first data point in the current chart. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Use chm.next.data.out() to retrieve information about the next and subsequent data points.
Arguments
option
Use this argument to indicate whether the function retrieves data for the absolute first data point or for the first data point that has been modified. The possible values are:
CHM_ALL_DATA
CHM_CHANGED_DATA
series_value
This returns the series to which the data point belongs.
category_value
This returns the category to which the data point belongs.
data_number
If there is more than one data point per category (a high-low graph, for example), this returns the sequence number of the data point within the category. If there is only one data point per category, the sequence number is 1.
data_value footnote_no
This returns the value of the data point.
This returns the number of the footnote (if any) associated with the data point.
Return values
CHM_OK success
CHM_ERROR error
Functions reference
5-19
Business Chart Manager
Context
3GL library function.
Syntax
long chm.first.data2domain.out( ref double series_value )
Description
Use this to check which is the first graph series that is linked to the second data domain of the current chart.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.first.footnote.out( ref long footnote_no, ref string footnote_text() )
Description
This returns information about the first footnote in the current chart. Use
the chart.
Arguments
footnote_no
This returns the footnote number.
footnore_text
This returns the footnote text.
Functions reference
5-20
Business Chart Manager
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.first.projection.out( ref double projection_point, ref long footnote_no )
Description
This retrieves information about the first projection point in the current chart.
Use chm.next.projection.out() to retrieve information about subsequent projection points in the chart.
Arguments
projection_point
This returns the position on the category axis where the projection point occurs.
footnote_no
This returns the number of the footnote associated with the projection point. It returns 0 if there is no footnote associated with the projection point.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-21
Business Chart Manager
Syntax
long chm.first.set.out( string set_name(16), ref long element_number, ref string element_name() )
Description
This retrieves information about the first element in the specified set. Use
Arguments
set_name element_no
The name of the set for which you want to retrieve information.
This returns the number of the first element in the set.
element_name
This returns the name of the first element in the set.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.footnote.in( long footnote_no, string footnote_text(80) )
Description
This function defines a footnote that can be used to annotate a data point or projection point.
Functions reference
5-22
Business Chart Manager
Arguments
footnote_no
The footnote number.
footnote_text
The footnote text.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.get.request( ref long chart_no, ref double category_from_value, ref double category_to_value )
Description
This retrieves a request from the Business Chart Manager. After calling the function, the application waits for a signal from the Chart Manager that a request is ready. It can then check the return value of the function to determine the nature of the request. The application must react to the request appropriately.
Arguments
chart_no category_from_value category_to_value
This returns the ID of the relevant chart, as returned by chm.open().
These indicate the range of data the Chart Manager is asking for. These arguments are relevant only when the return value is CHM_SOURCE_IN.
Functions reference
5-23
Business Chart Manager
Return Values
CHM_ABORT
CHM_SOURCE_IN
Quit the Business Chart Manager.
Send data to the Chart Manager. This value is returned when the user chooses the IN command on the Chart Manager’s File menu.
CHM_SOURCE_OUT Retrieve data from the Chart Manager. This value is returned when the user chooses the OUT command on the Chart Manager’s File menu.
CHM_TIMER Execute actions after the interval set by
< value > This is the ID of an application option defined in the
Application Options session (ttchm1120s000). When this value is returned, the application must execute the specific actions related to the particular application option.
Context
3GL library function.
Example
long request double category_from, category_to repeat request = chm.get.request(chartno, category_from, category_to) on case request case CHM_SOURCE_IN:
....
case CHM_SOURCE_OUT:
....
case CHM_TIMER: chm.draw() break case 200: start.session(MODAL, "ppmodggggmooo", "", "") endcase until (request = CHM_ABORT)
Functions reference
5-24
Business Chart Manager
Syntax
long chm.new( string chart_name(16), ref string chart_type() )
Description
This creates a new chart. The chart is not saved until the user executes the Save command.
Arguments
chart_name chart_type
The name of the new chart.
The chart type. If you do not specify an existing chart type, the Chart Manager selects the default chart type, as defined in the Chart Manager Application session (ttchm1500m000).
Return values
0
-1 success error
Context
3GL library function.
Syntax
long chm.next.data.out( long option, ref double series_value, ref double category_value, ref long data_number, ref double data_value, ref long footnote_no )
Description
You use chm.first.data.out() to retrieve information about the first data point in the current chart. You use chm.next.data.out() to retrieve information about the next data point in the same chart. To retrieve information about all subsequent data points, you can place this function in a loop that executes as long as the return value is CHM_OK.
Functions reference
5-25
Business Chart Manager
If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Arguments
option
Use this argument to indicate whether the function retrieves data for the absolute next data point or for the next data point that has been modified. The possible values are:
CHM_ALL_DATA
CHM_CHANGED_DATA
series_value
This returns the series to which the data point belongs.
category_value
This returns the category to which the data point belongs.
data_number
If there is more than one data point per category (a high-low graph, for example), this returns the sequence number of the data point within the category. If there is only one data point per category, the sequence number is 1.
data_value footnote_no
This returns the value of the data point.
This returns the number of the footnote (if any) associated with the data point.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.next.data2domain.out( ref double series_value )
Description
You use chm.first.data2domain.out() to retrieve the sequence number of the first graph series that is linked to the second data domain of the current chart.
You use chm.next.data2domain.out() to retrieve the sequence number of the
Functions reference
5-26
Business Chart Manager
next graph series that is linked to the second data domain of the same chart. To retrieve information about all subsequent graph series that are linked to the second domain, you can place this function in a loop that executes as long as the return value is CHM_OK.
If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.next.footnote.out( ref long footnote_no, ref string footnote_text() )
Description
Use chm.first.footnote.out to retrieve information about the first footnote in the current chart. Use chm.next.footnote.out() to retrieve information about the next footnote in the current chart. To retrieve information about all subsequent footnotes in the chart, you can place this function in a loop that executes as long as the return value is CHM_OK.
If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Arguments
footnote_no
This returns the footnote number.
footnore_text
This returns the footnote text.
Return values
CHM_OK success
CHM_ERROR error
Functions reference
5-27
Business Chart Manager
Context
3GL library function.
Syntax
long chm.next.projection.out( ref double projection point, ref long footnote_no )
Description
Use chm.first.projection.out to retrieve information about the first projection point in the current chart. Use chm.next.projection.out() to retrieve information about the next projection point in the same chart. To retrieve information about all subsequent projections in the chart, you can place this function in a loop that executes as long as the return value is CHM_OK.
If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Arguments
projection_point
This returns the position on the category axis where the projection point occurs
footnote_no
This returns the number of the footnote associated with the projection point. It returns 0 if there is no footnote associated with the projection point.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-28
Business Chart Manager
Syntax
long chm.next.set.out( string set_name(16), ref long element_number, ref string element_name() )
Description
Use chm.first.set.out() to retrieve information about the first element in a specified set. Use chm.next.set.out() to retrieve information about the next element in the set. To retrieve information about all subsequent elements in the set, you can place this function in a loop that executes as long as the return value is CHM_OK.
Arguments
set_name
The name of the set for which you want to retrieve information.
element_no
This returns the number of the next element in the set.
element_name
This returns the name of the next element in the set.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.open( string chart_name(16) )
Description
This opens the specified chart with its associated data.
Functions reference
5-29
Business Chart Manager
Return values
>0
0 the ID of the opened chart error; the Business Chart Manager cannot find or cannot open the specified chart
Context
3GL library function.
Syntax
long chm.projection.in( double projection_point, long footnote_no )
Description
This defines a projection point for the current chart.
Arguments
projection_point
This specifies the position on the category axis where the projection point occurs.
footnote_no
This specifies the number of the footnote (if any) associated with the projection point. Specify 0 here, if you do not want to associate a footnote with the point. You use
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-30
Business Chart Manager
Syntax
long chm.remove( string chart_manager(80), string owner_from(14), string owner_to(14) )
Description
This removes all charts from the chart list for the specified users. It is not necessary to start the Business Chart Manager in order to use this function.
Arguments
chart_manager
This specifies the name of a relevant Business Chart
Manager application. The name takes the following format: pp package code mmm module code xxx the name of the application
owner_from, owner_to
These specify the range of users for whom the charts are to be removed.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
void chm.scale.axis( double from_value, double to_value, long divisions, double factor, ref double domain_from_value, ref double domain_to_value, ref double divisionstep )
Description
This generates a scaling based on the minimum and maximum data values to be presented by the graph and on the number of divisions required. You can use the
Functions reference
5-31
Business Chart Manager
returned domain_from_value, domain_to_value, and divisionstep as inputs to
Arguments
from_value, to_value divisions factor domain_from_value, domain_to_value divisionstep
Use these to specify the minimum and maximum data values to be presented by the graph.
Use this to specify the number of divisions required.
The axis will be divided into the specified number of divisions.
This is a user-specified factor that determines the preciseness of the divisions.
The larger the factor, the more closely the
domain_from_value and the domain_to_value approach the from_value and to_value, and the greater the number of figures after the decimal point in the axis labels.
If the factor is small (for example, between 0 and 2), the figures in the axis labels are rounded to integers, tens, or hundreds, depending on the from_value, to_value and number of divisions.
The function calculates and returns these values, which are the minimum and maximum values of the domain.
These will be the start and end points of the axis.
This returns the size of the steps that separate the divisions on the axis.
Context
3GL library function.
Functions reference
5-32
Business Chart Manager
Syntax
long chm.select( string chart_manager(80), string title(80), long mode, string user(14), string owner(14), ref string chart_name(16), ref string chart_type(16) )
Description
This starts a session in which the user can select or create another chart or chart type. It is not necessary to start the Business Chart Manager in order to use this function.
Arguments
chart_manager
This specifies the name of a Business Chart Manager application. This corresponds to a particular record in the
Chart Manager application data session (ttchm1500m000).
The name takes the following format: pp package code mmm module code xxx the name of the application
title mode user owner
This specifies the window title.
This specifies whether the session enables selection or creation of a chart or chart type. The possible values are: n n n n
CHM_SELECT_CHARTTYPE select another chart type
CHM_CREATE_CHART create another chart
CHM_SELECT_CHART select another chart
CHM_CREATESELECT_CHART create or select another chart
This specifies the name of the user. The session is started with this user’s option set.
This specifies the name of the relevant owner. When a list of charts is called, the system displays the charts that this user owns.
Functions reference
5-33
Business Chart Manager
chart_name chart_type
This returns the name of the selected chart.
This returns the type of the selected chart.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.set.in( string set_name(16), ref long element_number, string element_name(80) )
Description
This adds an element to a specified set.
Arguments
set_name element_no
The name of the set to which the element is to be added.
The sequence number of the element within the set.
element_name
The description of the element.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Functions reference
5-34
Business Chart Manager
Syntax
long chm.set.option( long option, long flag )
Description
Use this to switch an application option on and off. Applications options are defined in the Applications Options session (ttchm1120s000). Actions can be linked to an application option using the chm.get.request function.
Arguments
option
The option that must be switched on or off.
flag
This specifies whether the option is be switched on or off. The possible values are: true false the option is enabled the option is disabled
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.set.timer( long time )
Description
This starts a timer. The Business Chart Manager sends a CHM_TIMER signal to the application every specified number of milliseconds. When the application retrieves the signal, it can perform appropriate actions (see chm.get.request()).
You can turn off the timer by calling chm.set.timer() with a time of zero.
Functions reference
5-35
Business Chart Manager
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.title.in( string main_title(80), string sub_title(80) )
Description
This function defines a main title and a subtitle for the current chart.
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
Syntax
long chm.title.out( ref string main_title(), ref string sub_title() )
Description
This retrieves the main title and subtitle of the current chart. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.
Functions reference
5-36
Business Chart Manager
Return values
CHM_OK success
CHM_ERROR error
Context
3GL library function.
#define CHART.NAME "RESULT"
#define CHART.APPLICATION "ttchmtest"
#include <bic_chartman> long chart.data(2,4) function main()
{ long chno string chart_type(16)
| start Chart manager chm.chartman(CHART.APPLICATION, "Title", "user1", "") chno = chm.open(CHART.NAME, chart_type) if chno > 0 then send.chart.data() | define data endif chm.draw() | draw chart get.chart.data(chno) | store data
}
| define data, send it to Chart manager function void send.chart.data( )
{ double series, category long no_1, no_2, no_3, no_4
| Chart title chm.title.in("Financial Results", "")
| Set definitions no_1 = 1 no_2 = 2 no_3 = 3 no_4 = 4
Functions reference
5-37
Business Chart Manager
chm.set.in("Series", no_1, "Company 1") chm.set.in("Series", no_2, "Company 2") chm.set.in("Categories", no_1, "Qrtr I") chm.set.in("Categories", no_2, "Qrtr II") chm.set.in("Categories", no_3, "Qrtr III") chm.set.in("Categories", no_4, "Qrtr IV")
| Domain definitions chm.domain.in(CHM_SERIES_DOMAIN, CHM_SET,
"Series", "Companies", "Unit", 1.0, 2.0, 1.0, "") chm.domain.in(CHM_CATEGORY_DOMAIN, CHM_SET,
"Categories", "Quarters", "1993", 1.0, 4.0, 1.0, "") chm.domain.in(CHM_DATA_DOMAIN, CHM_REAL, "", "Result",
"x 1000", 0.0, 100.0, 0.01, "ZZZZZ9V,99")
| Axis data chm.axis.in(CHM_SERIES_AXIS, FALSE, 0, 2, 1.0, 0.0, "") chm.axis.in(CHM_CATEGORY_AXIS, FALSE, 0, 4, 1.0, 0.0, "") chm.axis.in(CHM_DATA_AXIS, FALSE, 0, 10, 10.0, 0.0, "") get.data.from.table(chart.data()) | user defined
} for series = 1 to 2 for category = 1 to 4 | Data values chm.data.in(series, category, 1, chart.data(series, category), 0) endfor endfor
| get data from Chart manager function void get.chart.data( long chart_no)
{ long datn, footnote_no, ret, request double catv, data, serv, category_from, category_to repeat request = chm.get.request( chart_no,category_from,
category_to) on case request case CHM_SOURCE_OUT: | OUT-command Chart manager ret = chm.first.data.out(CHM_ALL_DATA,
serv, catv, datn, data, footnote_no) while (ret = CHM_OK) chart.data(serv, catv) = data ret = chm.next.data.out(CHM_ALL_DATA,
serv, catv, datn, data, footnote_no)
Functions reference
5-38
Business Chart Manager
endwhile put.data.in.table(chart.data()) | user defined break endcase until (request = CHM_ABORT)
}
axis axis label back plane bar chart
One of two or more reference lines, positioned at right angles to each other, against which data values are plotted. In mathematics,
X, Y, and Z axes are used. The Chart Manager uses four axes: category axis as x axis data axis as y axis series axis data axis II as z axis as second y axis
You use data axis II when you want to draw two series to different scales in the same graph.
This indicates the meaning or value of a major division on the axis.
The plane behind the graph (that is, the background).
A graph in which a vertical or horizontal bar represents each data value. Bars representing the same series have the same color, pattern, and width. The higher the bar, the higher the value at that point. The bar width and thickness (3D only) can be set per series.
Bars representing different series can overlap wholly or partially.
The plane below the graph.
bottom plane category chart
Measuring points are divided into categories. For example, when plotting the quarterly expenditures in a particular year, each quarter is regarded as an information category. Category values are measured on the x-axis. In pie charts, each segment can be regarded as a category, depending on the way the data is sorted.
A chart is a graphical presentation of information. A chart displays a pie and/or graph including title, legend, and footnotes.
Functions reference
5-39
Business Chart Manager
Chart
Manager
Chart
Manager application chart type
A tool within the BaanERP application, which presents data in graphs and pie charts.
A collection of charts, user option sets and window preferences.
The Chart Manager needs this information for its operation.
data
The chart type specifies the attributes of a chart – for example, the graph type, the thickness of lines and bars, colors, and fonts.
These settings are data- independent.
The information presented in the chart – for example, the domains used, the data point values, and so on.
data label The name or the value of a data point.
data number The sequence number of a data point within a category.
data point division
A point in the chart representing a value, and displayed, for example, as a symbol, a bar, a pie segment, or a kink in a line.
The axes of a graph are divided into a number of major and minor divisions. These divisions are marked by ticks. Grids and labels are assigned by major division.
Special labels at major divisions. These replace the values from the domain associated with the axis.
division labels domain A range with a start value, end value and step size. These indicate which values are legal. There are data, category, and series domains.
domain type In the Chart Manager there are three domain types: exploded footnote n n n integer the domain consists of a series of integers real the domain consists of both fractions and integers enumerated set the domain consists of a set of labels
A detached pie segment. You can use this option to draw attention to one of the segments. The distance from the segment to the pie center can be specified as a percentage of the pie's radius.
Information relating to a data point or projection point. Footnotes are placed in a separate box in the chart.
Functions reference
5-40
Business Chart Manager
footnote label footnote number graph grid hilo (highlow) graph hilo selects histogram
The text placed in a footnote box.
The number or the series of asterisks placed at the data point or projection point and referring to the same number or series of asterisks in the footnote box.
A graphical presentation of information drawn within a set of axes.
A pattern of lines at right angles to each other and the axis. They connect the values in the graph with the points on the vertical and horizontal axes. Grid lines are drawn at major divisions only.
A hilo graph contains multiple data points per category, each data point having its own meaning. For each category there may, for example, be a data point representing the maximum value and one representing the minimum value. This type of graph is very suitable, for example, for monitoring stock market developments.
Symbols in a hilo graph indicating where in a category a particular data point is located.
A histogram consists of a set of stacked blocks, each block representing a particular data value.
intersection point legend
The value on the data axis where category axis and data axis intersect.
An explanation of the chart. The legend contains a sample of each series (bar, line, pie, etc.) in the chart with a description of the series.
line In a line graph, the data points for each series are connected by a line. There are four types of lines: curve, linear, stepped and wire.
Line graphs are mainly used to show trends.
A line graph in which data points are joined by straight lines.
linear logarithmic A scaling in which the axis is divided into equal sections that do not represent equal steps in a scale of values. Instead the divisions increase by a specified factor. Logarithmic scales are useful when there is a wide range of values.
option set owner
A number of possibilities or limitations per user or group.
The creator of the chart. Users can modify only their own charts.
Functions reference
5-41
Business Chart Manager
percent label pie
The proportion of the total pie value represented by a pie segment.
Circular diagram divided into segments showing the quantitative relationship between different series or categories. The pie represents the total value. Pies are the only graphs that are not axis-oriented.
pie segment A part of the pie. Each segment represents a percentage of the total pie.
projection A way of presenting a graph in which the graph is split up in different parts referred to as projection areas. Each projection area has its own attributes. A series can be shown by a different graphical means in each projection area. The use of several projection areas is a convenient means to distinguish between measured and expected (projected) values in a series. Projection areas are separated by a projection line, which is placed at right angles to the category axis.
projection point scale second data axis
The point on the category axis where the projection line and the category axis intersect.
The size of the graph or pie as a percentage of the box size.
The fourth axis of the Chart Manager’s coordinate system. It has the same dimensions as the data axis (y-axis). The second data axis is always used in combination with the first data axis when two (or more) different series must be drawn to different scales in the one chart.
The second data domain is used for the second data axis.
second data domain series set side plane stepped
A set of related data points that are linked graphically. In a line graph, for instance, they are connected by a line. This line indicates which data points constitute one series.
A group of labels.
The plane beside the graph.
symbol
A line graph in which the line consists of horizontal and vertical sections. Stepped lines draw attention to changes in the level of data values.
A sign indicating where a data point is located.
Functions reference
5-42
Business Chart Manager
ticks title unit label wire
Signs indicating the divisions on the axis. Ticks at major divisions are larger than those at minor divisions.
In the Chart Manager there are four types of titles: n
The description of the Chart Manager application. This appears at the top of the form together with the package and module codes.
n
Main title (placed in the title box).
n
Subtitle (placed in the title box).
n
Axis title. This is the description of an axis and is the same as the domain label.
The description of the unit (measure or quantity) in which categories, data or series are expressed. The label is placed beside the relevant axis.
A line graph in which the data points of different series are connected by lines, the result being a kind of mountain landscape.
This is possible in 3-D graph only.
Functions reference
5-43
Business Chart Manager
Functions reference
5-44
This section describes functions that are relevant to character-based windows only. You do not use these functions to handle graphical windows.
Note
The functions for sending data and instructions to the screen or printer all return a string that you can print by calling the print() function or that you can use in a string expression. When you use print() with these functions, only the internal screen is updated. You must call refresh() to update the terminal screen.
string bc$ string bg$ void box string bs$ string cf$ void void change.window
cl.screen
string cp$ string cr$ string cs$ long current.window
void data.input
void del.window
string delch$ string deleteln$
( long type, long rows, string barcode(.) )
( long color )
( long box_x, long box_y, long box_width, long box_height, long mode )
( [num_expr] )
( num_expr )
( long wind_id )
( long column, long row, long no_of_cols, long no_of_rows )
( long column, long row )
( )
( [num_expr] )
( )
( string options(.), ref string result(.), string default(.) [, ref long event(EVTMAXSIZE), ref long char_value )
( long wind_id )
( num_expr )
( num_expr )
Functions reference
6-1
Character-based windows
void dump.window
string el$ string es$ string ff$ string fg$ void first.window
string keyin$ void last.window
string lf$ void long map.window
mark.handler
void long move.window
new.window
( [long wind_id] )
( )
( )
( )
( long color )
( long wind_id ) string fs$ long get.col
( [num_expr] )
( ) void long long get.cp
( ref long x, ref long y ) get.row
( ) get.window.attrs
( long wind_id, ref long attrs(WINMAXSIZE) ) string insch$ string insertln$
( string_expr )
( string_expr )
( [99] )
( long wind_id )
( [num_expr] )
( long wind_id )
( ref long mark.table() )
( long col, long row )
( long height, long width, long row, long col )
( long wind_id )
( num_expr ) void no.scroll
string pc$ string pf$ void void refresh resize.window
void void scroll set.bg.color
void set.fg.color
string sf$ long sub.window
string void void tab$ unmap.window
wrebuild
( num_expr )
( [long wind_id] )
( long width, long height )
( long wind_id )
( long wind_id, long color )
( long wind_id, long color )
( num_expr )
( long parent_wind, long height, long width, long row, long col)
( num_expr )
( long wind_id )
( long mode )
Functions reference
6-2
Character-based windows
Syntax
string bc$( long type, long rows, string barcode(.) )
Description
Use this to create a barcode of the specified type.
Arguments
type
This points to a shell script that generates the barcode. The script is stored in the barcode directory; this is specified in the printer information file. The script names take the form ‘typexx’, where xx is a two digit number. For example ‘type02’. You specify the two digit number in this argument.
rows
The height of the barcode, as a number of lines.
barcode
The string that must be converted to a barcode and printed.
Context
Bshell function.
Example
print bc$( 02, 2, input_string ) refresh()
Syntax
string bg$( long color )
Description
Use this to set the background color of the current window. The color argument can have the following values:
CW.BLACK
CW.RED
CW.BLUE
CW.MAGENTA
CW.GREEN
CW.YELLOW
CW.CYAN
CW.WHITE
Functions reference
6-3
Character-based windows
Context
Bshell function.
Example
print bg$( CW.RED ) refresh()
Syntax
void box ( long box_x, long box_y, long box_width, long box_height, long mode )
Description
This draws a rectangle on the screen. If the specified box does not fit in the current window, only the part that does fit is displayed.
Changes become visible on screen only after calling refresh().
Arguments
box_x, box_y
The screen co-ordinates for the top left corner of the box.
width, height
The width and height respectively of the box.
mode
0 only the box is drawn; no other screen modifications are made the interior of the box is cleared 1
2 the box is drawn dimmed; no other screen modifications are made the box is drawn dimmed and its interior is cleared 3
In addition to the above values, you can specify special effects such as reversed and blinking. For a list of possible attributes, see cf$(). To use these attributes, you must multiply the attribute number by 10, and then add one of the above mode values.
Context
Bshell function.
Functions reference
6-4
Character-based windows
Examples
| This draws the largest possible box box( 1, 1, 80, 23, mode ) refresh()
| This draws a box with the reverse attribute cf_mode = 41 | attribute 4 (* 10) + mode 1 box( 2, 2, 40, 13, cf_mode ) refresh()
Syntax
string bs$( [long num_expr] )
Description
Use this to position the cursor num_expr positions to the left. If you do not specify the num_expr argument, the default number of positions is 1.
Context
Bshell function.
Example
print bs$(4) | Move cursor 4 positions to the left refresh()
Syntax
string cf$( long attribute_code )
Description
Use this to send a control code to the current window or printer. All characters after the command are printed or displayed in the font associated with the control code. To reset the font to normal, call cf$(0)
.
Functions reference
6-5
Character-based windows
The following codes are available:
12
13
14
15
8
9
10
11
6
7
4
5
2
3
0
1
normal
bold
blinking
bold blinking
reverse
bold reverse
blinking reverse
bold blinking reverse
underscore
underscore bold
underscore blinking
underscore bold blinking
underscore reverse
underscore reverse bold
underscore reverse blinking
underscore reverse bold blinking
normal bold bold bold reverse bold reverse bold reverse bold reverse underscore underscore bold underscore bold underscore bold underscore reverse underscore bold reverse underscore bold reverse underscore bold reverse
Note
If the printer is unable to print in reverse, text is printed in bold instead. Blinking is possible only on ASCII terminals.
Context
Bshell function.
Example
| To screen print cf$(4),"This is reversed printing on the screen",cf$(0)
| To printer spool.pr.line = cf$(4)&"Printed reverse"&cf$(0) spool.line()
Functions reference
6-6
Character-based windows
Syntax
void change.window( long wind_id )
Description
This makes the specified window current. This does not affect the screen display.
Context
Bshell function.
Syntax
void cl.screen( long column, long row, long no_of_cols, long no_of_rows )
Description
This clears a specified area of the current window. The changes become visible on screen only after you call refresh().
Arguments
column, row
The column and row co-ordinates for the top left corner of the area to be cleared.
no_of_cols no_of_rows
The number of columns to be cleared.
The number of rows to be cleared.
Context
Bshell function.
Example
cl.screen( 1, 5, 80, 6 ) refresh()
Functions reference
6-7
Character-based windows
Syntax
string cp$( long column, long row )
Description
Use this to position the cursor at the specified column and row. The cursor position is always relative to the upper left corner of the current window.
Context
Bshell function.
Syntax
string cr$()
Description
Use this to send a carriage return (without a line feed) to the screen or printer.
The cursor is positioned at column 1 of the current line.
Context
Bshell function.
Syntax
string cs$( [num_expr] )
Description
Use this to change the window size and/or clear the window. The num_expr argument can have one of the the following values:
0 clear current window
1 clear current window (default value)
2 set screen to 80 columns and clear current window
Functions reference
6-8
Character-based windows
3 set screen to 132 columns and clear current window
4 set screen to 80 columns without clearing current window
5 set screen to 132 columns without clearing current window
Context
Bshell function.
Syntax
long current.window()
Description
This returns the identification number of the current window.
A window becomes current when it is created or when you call
current window.
Context
Bshell function.
Syntax
void data.input( string options(.), ref string result(.), string default(.) [, ref long event(EVTMAXSIZE), ref long char_value )
Description
This reads data from the keyboard.
If the function specifies a default value, that value is displayed on screen. The value is accepted when the user presses ENTER. However, if the user enters a character at the first position in the field, the default value is deleted.
Functions reference
6-9
Character-based windows
Normally, characters typed by the user are inserted before the current cursor position. However, if option ‘C’ is included in the options argument, characters typed by the user are inserted at the current cursor position.
Users can edit the default value or make minor corrections to the string entered
(before they press ENTER) by using the following keys:
→
←
Scroll right.
Scroll left.
DEL Delete character at cursor position. Characters to the right of the deleted character are moved one position to the left. If the cursor is positioned beyond the last character, this character is deleted and the cursor moves one position to the left. Pressing DEL in an empty field redisplays the default value.
CTRL+X Clear field.
TAB Delete all characters from the cursor position to the end of the field.
Arguments
options
This argument must either be empty or it must contain 5 parts separated by one or more spaces.
If it is empty, the following input characteristics apply:
−
no fill characters are displayed
−
input starts at the current cursor position
−
all characters are permitted
−
the maximum number of characters that can be input is
132
If it is not empty, it must include the following five items:
−
the starting column
−
the starting row
−
the minimum length of the string to be read
−
the maximum length of the string to be read
−
zero or more options
The following options are available. You can specify them with or without separating spaces.
+ABIDI Supports input of bidirectional data.
B Empty result not permitted.
Functions reference
6-10
Character-based windows
C
E
G
K
Overwrite mode.
E and e permitted as input; always converted to capital letter.
F Effect of ‘.’ (moving cursor to previous field) is switched off.
FILL='.' The specified character is used as the fill character for the field. By default, the fill character defined for the user is used.
A floating-point number is expected.
Converts all uppercase characters to lower case.
L='..' Characters specified by this option are interpreted as the end of input. When the user enters one of these characters, data.input() returns immediately without waiting for the user to press ENTER. The char_value argument returns the decimal value of the character that was typed.
You can specify any combination of the following characters with this option:
−
ASCII characters A - Z, a - z, and others such as
% & ! ?.
−
Octal representation of characters; these must start with ‘\0’. For example: \01 and \012.
−
Decimal representation of characters; these must start ‘\’. For example: \1 and \12.
−
Hexadecimal representation of characters; these must start with ‘\0x’. For example: \0x1and
\0x12.
−
Control characters. For example: ^B and ^F.
−
Backslash
−
Circumflex
−
Escape (\E or \e).
−
Space (\s).
−
New line,(\n).
−
Return
−
Form feed (\f).
−
Previous line (\v).
−
Backspace (\b).
Functions reference
6-11
Character-based windows
N
P
The following example specifies the following characters: A, B, C, octal 13, Control+N, Control+P,
Esc, new line, and backslash.
L=’ABC\013^N^P\E\n\\’
LEN=’..’ This specifies the available space on the terminal screen. If the cursor is at the beginning or end of the available space, the field scrolls horizontally.
R
T=’..’
U
V=’..’
An integer number is expected.
Entered characters are suppressed. No default value or fill characters are displayed on screen.
An automatic carriage return is executed when the last character is entered (that is, when the string is full).
A string specifying all valid input characters. All other characters are invalid.
Converts all lowercase characters to uppercase.
Y
>
<
A string specifying all invalid characters. All other characters are valid.
Result must be ‘Y’ or ‘N’. Lowercase characters are converted to uppercase, so ‘y’ and ‘n’ are also permitted. If these characters are not specified with
T=’YyNn’, other characters are also permitted. But after the user presses ENTER, the message ‘Only Y/N allowed’ is displayed.
After the user presses ENTER, the input string is right justified.
After the user presses ENTER, the input string is left justified.
result
This returns the value typed by the user. The argument must be declared as a one-dimensional string.
A default string that is displayed on screen.
default event
If the function is stopped as a result of an event, that event is stored in this argument. See Chapter 17, Events.
char_value
If the function is stopped by input of a special character, the character typed is stored in this argument.
Functions reference
6-12
Character-based windows
See also
keyin$()
Context
Bshell function.
Example
string result(1) data.input("0 0 1 1 UE T=’YN’", result, "")
Syntax
void del.window( long wind_id )
Description
This deletes the specified window. When you delete the current window, the next window in the internal window stack becomes the current one. The screen is not refreshed automatically.
Context
Bshell function.
Syntax
string delch$( num_expr )
Description
Use this to delete num_expr characters, from the current cursor position to the right. The text following the deleted characters shifts num_expr positions to the left.
Context
Bshell function.
Functions reference
6-13
Character-based windows
Syntax
string deleteln$( num_expr )
Description
Use this to delete num_expr lines, from the current line down. Lines below the deleted ones are moved up.
Context
Bshell function.
Syntax
void dump.window( [long wind_id] )
Description
This sends the specified window to the printer spooler. If you do not specify a window, the ID of the current window is sent. The user must choose the required spooler.
Context
Bshell function.
Syntax
string el$()
Description
Use this to erase all characters from the current character to the end of the line.
The cursor position is not changed.
Functions reference
6-14
Character-based windows
Context
Bshell function.
Syntax
string es$( )
Description
Use this to erase all characters from the current cursor position to the end of the screen. The cursor position is not changed.
Context
Bshell function.
Syntax
string ff$( )
Description
Use this to send a form feed to the printer. The result of this function cannot be sent to the screen.
Context
Bshell function.
Example
spool.pr.line = ff$() spool.line()
Functions reference
6-15
Character-based windows
Syntax
string fg$( long color )
Description
Use this to set the foreground color of text, starting at the current cursor position.
The color argument can have the following values:
CW.BLACK
CW.RED
CW.BLUE
CW.MAGENTA
CW.GREEN
CW.YELLOW
CW.CYAN
CW.WHITE
Context
Bshell function.
Syntax
void first.window( long wind_id )
Description
This places the specified window above all other windows on the screen. The window is also placed at the first position in the internal window stack. The alterations become visible on screen only when you call refresh() or
Context
Bshell function.
Functions reference
6-16
Character-based windows
Syntax
string fs$( [num_expr] )
Description
Use this to move the cursor num_expr positions to the left. If you exclude the
num_expr argument, the cursor is moved one space to the left.
Context
Bshell function.
Syntax
long get.col()
Description
This retrieves the number of the column where the cursor is currently positioned.
The function uses get.cp(), so it is slower than that function.
Context
Bshell function.
Syntax
void get.cp( ref long x, ref long y )
Description
This stores the coordinates of the current cursor position in the x and y arguments.
Context
Bshell function.
Functions reference
6-17
Character-based windows
Syntax
long get.row()
Description
This retrieves the number of the row where the cursor is currently positioned.
The function uses get.cp(), so it is slower than that function.
Context
Bshell function.
Syntax
long get.window.attrs( long wind_id, ref long attrs(WINMAXSIZE) )
Description
This stores attributes of the specified window in the attrs array. The maximum number of attributes that can be retrieved is indicated by the predefined constant
WINMAXSIZE.
You can retrieve the attributes with the following predefined variables: win.parent( attrs ) window ID of parent window win.x( attrs ) win.y( attrs ) x-position of window y-position of window win.width( attrs ) win.height( attrs ) width of window height of window win.border.width( attrs ) border width of window (gwindow only) win.background( attrs ) background color of window win.event.mask( attrs ) mask indicating the events generated by the window
Functions reference
6-18
Character-based windows
Return values
TRUE success
FALSE error
Context
Bshell function.
Syntax
string insch$( string_expr )
Description
Use this to insert the result of string_expr at the current cursor position. The characters to the right of the cursor are moved string_expr positions to the right.
Context
Bshell function.
Syntax
string insertln$( string_expr )
Description
Use this to insert the result of string_expr on a new line, above the current line.
The current and succeeding lines are moved down.
Context
Bshell function.
Functions reference
6-19
Character-based windows
Syntax
string keyin$( [99] )
Description
This reads the first character from the keyboard buffer. If there is no character in the buffer, the function waits until one is entered.
If you include the optional argument, the function performs a non-blocking read.
If there is no character in the buffer, the function returns immediately with an empty string. This form of the function is used for interrupting a batch process when the user presses a key.
The function converts the following function keys to ASCII characters:
KEY_LEFT
KEY_RIGHT
KEY_UP
KEY_DOWN
KEY_INSERT
BS
FF
VT
LF
EM
8
12
11
10
25
^H
^L
^K
^J
^Y
Return values
The character read from the event queue. If the returned string contains multiple bytes, the character is s multibyte character. If the character is a function that cannot be converted, the function returns an empty string.
Context
Bshell function.
See also
Chapter 17, Events data.input()
Functions reference
6-20
Character-based windows
Example
repeat
...
until (keyin$(99)=chr$(27)) | until <Esc> is pressed
Note that the above example is very time consuming.
Syntax
void last.window( long wind_id )
Description
This places the specified window below all other windows on the screen. The window is also placed at the last position in the internal window stack. The alterations become visible on screen only when you call refresh() or
Context
Bshell function.
Syntax
string lf$( [num_expr] )
Description
Use this to send one or more line feeds to the screen or printer. The cursor is moved down num_expr lines. If you do not specify a number of lines, the cursor is moved down one line.
Context
Bshell function.
Functions reference
6-21
Character-based windows
Syntax
void map.window( long wind_id )
Description
This makes the specified window visible, without changing the order of the windows.
Context
Bshell process.
Syntax
long mark.handler( ref long mark.table() )
Description
This enables a user to mark one or more records on an ASCII form. On return, the mark.table argument indicates which records are marked. Each element in the
mark.table array corresponds to a record on the form. If an array element is set to
1, the corresponding record is marked. If it set to 0, the corresponding array element is not marked.
The predefined variables marked and mark.status are not affected by this function.
Return values
0
1 no records marked one or more records marked
Context
4GL library function.
You can use this function only in 4GL scripts, and only in choice and form sections of those scripts. You cannot use it in programs of type 4.
Functions reference
6-22
Character-based windows
See also
mark.occ()
Example
| if records 3 and 8 are marked, the following is true
| mark.table(3) = 1
| mark.table(8) = 1
| other elements are 0 (false) for i=1 to filled.occ
if mark.table(i) then do.occ(i, some_function) endif endfor
Syntax
void move.window( long col, long row )
Description
This moves the current window to a specified position (relative to the top left corner of the parent window). There is no need to refresh the window.
Context
Bshell function.
Syntax
long new.window( long height, long width, long row, long col )
Description
This creates a new window. The new window automatically becomes the current window.
Functions reference
6-23
Character-based windows
Arguments
height, width
The height and width of the new window.
row, column
These indicate the position of the top left corner of the new window, relative to the top left corner of the parent window.
Return values
The window ID for the new window.
Context
Bshell function.
Syntax
void no.scroll( long wind_id )
Description
This disables scrolling for the specified window.
Context
Bshell function.
Syntax
string pc$( num_expr )
Description
Use this to set certain printer codes. The following printer codes are available:
1
4
7 paper bin 1 paper bin 4 usr1
2
5
8 paper bin 2 landscape
3
6 usr2 . . . . . .
22 paper bin 3 portrait usr16
You define codes 9 to 22 in the printer information file for the particular printer
(for example, $BSE/lib/printinf/m/m290).
Functions reference
6-24
Character-based windows
Context
Bshell function.
Syntax
string pf$( num_expr )
Description
Use this to change the printer font settings. The following settings are available:
7
8
5
6
3
4
1
2
.
.
9
10
24
.
.
large small middle dblwide nlq italic superscript subscript font1 font2 font16
You define settings 9 to 24 in the printer information file of the particular printer
(for example, $BSE/lib/printinf/m/m290).
Context
Bshell function.
Example
spool.pr.line = pf$(2) spool.line() | Set printer to small font
Functions reference
6-25
Character-based windows
Syntax
void refresh( [long wind_id] )
Description
This copies the internal screen to the terminal screen. The internal screen is modified by any function which sends data to the screen (for example, print(),
If you specify a window ID, the specified window is refreshed. But the window sequence is not changed. If you do not specify a window ID, the current window is refreshed and placed above all other windows on the screen.
Context
Bshell function.
Syntax
void resize.window( long width, long height )
Description
This resizes the current window. You must specify the new width and height in pixels. There is no need to refresh the window.
Context
Bshell function.
Functions reference
6-26
Character-based windows
Syntax
void scroll( long wind_id )
Description
This enables scrolling for the specified window. By default, windows do not scroll.
Context
Bshell function.
Syntax
void set.bg.color( long wind_id, long color )
Description
This sets the background color of a specified ASCII window. The color argument can have the following values:
CW.BLACK
CW.RED
CW.BLUE
CW.GREEN
CW.CYAN
CW.GRAY
CW.MAGENTA CW.YELLOW
CW.WHITE
Context
Bshell function.
Syntax
void set.fg.color( long wind_id, long color )
Description
This sets the foreground color of a specified ASCII window. The color argument can have the following values:
Functions reference
6-27
Character-based windows
CW.BLACK CW.BLUE
CW.RED
CW.MAGENTA
CW.GREEN CW.CYAN CW.GRAY
CW.YELLOW CW.WHITE
Context
Bshell function.
Syntax
string sf$( num_expr )
Description
Use this to set all text on the screen to bold. Use sf$(0)
to reset the screen to normal.
Context
Bshell function.
Syntax
long sub.window( long parent_wind, long height, long width, long row, long col )
Description
This creates a new window in the specified parent window.
Arguments
parent_window
The ID of the parent window.
height, width
The height and width of the new window.
row, col
These indicate the position of the top left corner of the new window, relative to the top left corner of the parent window.
Return values
The window ID for the new window.
Functions reference
6-28
Character-based windows
Context
Bshell function.
Syntax
string tab$( num_expr )
Description
Use this to position the cursor at a specified column in the current window. If you use this function in the variable spool.pr.line for the function spool.line(), the printer is set to column num_expr.
Context
Bshell function.
Syntax
void unmap.window( long wind_id )
Description
This hides the specified window.
Context
Bshell function.
Syntax
void wrebuild( long mode )
Description
This redraws the entire screen. The mode argument can have one of the following values:
Functions reference
6-29
Character-based windows
0
1 all windows are refreshed the screen is cleared and all windows are rebuilt
Context
Bshell function.
Functions reference
6-30
Use these functions to perform various operations on client files – for example: n n n n n
To open, read, write to, close, and delete files on a client
To transfer files between client and server
To retrieve client file information
To create and delete directories on a client
To start an application on a client
Note
You can use these functions only with the BW interface, and not with BI.
long long void void long long long long
long app_start long long app_status client2server create.local.
directory remove.local.
directory remove.local.
file seq.close.local
seq.fstat.local
seq.open.local
seq.read.local
seq.write.local
( string commandline, string directory, string stdin, string stdout, string stderr )
( long app.id )
( string source, string dest, long text.mode [, long rm.file]
[, long progress.window] )
( string dirent )
( string dirent )
( string filename )
( long lfn )
( string filename, ref long nr.bytes )
( string filename, string mode(2)
[, long remove.after.use] )
( ref string buf, ref long size, long lfn )
( string buf, long size, long lfn)
Functions reference
7-1
Client file access
long server2client ( string source, string dest, long text.mode [, long progress.window] )
Syntax
long app_start( string commandline, string directory, string stdin, string stdout, string stderr )
Description
This starts the application specified in the commandline argument. It returns an
ID for the started application. You can subsequently use this ID as the app.id argument in the app_status() function.
Arguments
commandline
This specifies the command that starts the application. If
commandline does not include a directory path, Windows searches for the executable file in the following directories, in the order shown below:
1
The directory where BW is loaded.
2
The Windows system directory.
3
The Windows directory.
4
The directories listed in the PATH environment variable.
directory stdin
The default working directory for the application.
The standard input file name.
stdout stderr
The standard output file name.
The standard error file name.
Notes
If commandline specifies the name of a nonexecutable file, Windows starts the application with which the file name extension is associated. For example, if
commandline is c:\temp\file.txt, and .txt is associated with the Notepad application, Windows will start Notepad. Because users can change the
Functions reference
7-2
Client file access
association of a file name extension, you cannot predict which application will start.
This functionality is not available when you specify standard input, output, and error files.
Return values
>=0 success; identification number of the started application is returned
<0 error (that is, the negative value of the system error)
Context
ttdllbw library function.
Syntax
long app_status( long app.id )
Description
This retrieves information about a specified application.
Arguments
app.id
The ID of the application for which you want to retrieve information, as returned by app_start().
Return values
<>0 success; application is running
0 error; application is not running – probably crashed after activating
Context
ttdllbw library function.
Functions reference
7-3
Client file access
Syntax
long client2server( string source, string dest, long text.mode [, long rm.file] [, long progress.window] )
Description
This copies a specified file from the client to the server. The function supports long file names.
Arguments
source dest
The source file name, on the client.
The destination file name, on the server.
text.mode
This is a boolean value that specifies whether the file is to be copied in text or binary mode:
<>0 text mode
0 binary mode
rm.file
Use this optional argument to specify whether the source file must be deleted after it has been copied:
<>0 source file is deleted
0 source file is not deleted
progress.
window
Use this optional argument to specify whether a progress indicator must be displayed to indicate the progress of the copy action:
<>0 progress indicator is displayed
0 progress indicator is not displayed
Notes
In order to use a progress indicator, you must first create it with
change its value. If you specify the PROGRESS.STOP and/or
PROGRESS.CANCEL modes when creating the indicator, the user can stop or cancel the copy operation before it has completed. In both cases, the destination file is deleted.
Functions reference
7-4
Client file access
Return values
0
1
<0 success error; process canceled by the user error; source file not copied to the destination file
Example
client2server( bse.tmp.dir$() & "/test1.txt", "C:\Program
Files\Test.txt", false, false )
Context
ttdllbw library function.
Syntax
long create.local.directory( string dirent )
Description
This creates a specified directory on a client system. You must have write permission in the parent directory to do this. Access permissions for the new directory are set to read, write, and execute for all users.
The function supports long file names.
Arguments
dirent
The directory name. This must include the full path to the directory, including the drive name. For example: create.local.directory("C:/Program Files/mydir")
Return values
0 success
<>0 error; probably no permission
Context
ttdllbw library function.
Functions reference
7-5
Client file access
Syntax
long remove.local.directory( string dirent )
Description
This deletes a specified directory on the client system. The function supports long file names.
Arguments
dirent
The directory name. The name must include the full path to the directory, including the drive name. For example: remove.local.directory("C:/Program Files/Mydir")
Return values
0 success
<>0 error; probably no permission
Context
ttdllbw library function.
Syntax
void remove.local.file( string filename )
Description
This deletes a specified file on the client system. The function supports long file names.
Arguments
filename
The name of the file that must be deleted. The name must include the full path to the file, including the drive name. For example: remove.local.file("C:/Program Files/Mydir/
Myfile.txt")
Functions reference
7-6
Client file access
Context
ttdllbw library function.
Syntax
void seq.close.local( long lfn )
Description
This empties the buffers associated with the specified file and closes the file. If the remove.after.use flag was set when the file was opened, the file is removed after it is closed.
Arguments
lfn
The file pointer to the file that must be closed, as returned by
Notes
You cannot use seq.*() functions in combination with the seq.*.local() functions.
So, you cannot use seq.close.local() on a file that was opened with seq.open().
Context
ttdllbw library functions.
Syntax
long seq.fstat.local( string filename, ref long nr.bytes )
Description
This retrieves information about a specified file on a client system. The function supports long file names.
Functions reference
7-7
Client file access
Arguments
filename
The name of the file. If you do not specify a path name, the file is searched for in the directory where BW is loaded.
nr.bytes
This returns the size of the file in bytes.
Notes
You cannot use seq.*() functions in combination with the seq.*.local() functions.
So, you cannot use seq.fstat.local() on a file that was opened with seq.open().
Return values
>=0 success
<0 error; probably file does not exist
Context
ttdllbw library function.
Example
seq.fstat.local("C:\Program Files\Test.txt", len.in.bytes)
Syntax
long seq.open.local( string filename, string mode(2), [long remove.after.use] )
Description
This opens a specified file on the client system. It returns a file pointer, which you can use to identify the file in subsequent operations. The function supports long file names.
Functions reference
7-8
Client file access
Arguments
filename mode remove.after.use
The name of the file that must be opened. If you do not specify a path name, the file is searched for in the directory where BW is loaded.
The mode in which the file must be opened. This can be one of the following options:
"r" Open for reading.
"w" Create for writing.
"a" Open for writing at end of file, or create for writing.
In addition, you can add "t" to any of the above options if you want the file to be opened in text mode.
Use this optional argument to specify whether or not the file must be removed after it has been closed by
<>0 file is removed
0 file is not removed
Note
You cannot use seq.*() functions in combination with the seq.*.local() functions.
So, you cannot use seq.seek() or seq.rewind(), for example, on a file that was opened with seq.open.local().
Return values
>0 success; file pointer is returned
<=0 error; file could not be opened
Context
ttdllbw library function.
Example
seq.open.local("C:\Program Files\Test.txt", "rt", false)
Functions reference
7-9
Client file access
Syntax
long seq.read.local( ref string buf, ref long size, long lfn )
Description
This reads a specified number of bytes from a specified file into buf.
Arguments
buf
This returns the data read from the file.
size
This returns the number of bytes read from the file.
lfn
The file pointer, as returned by seq.open.local() when the file was opened.
Note
You cannot use seq.*() functions in combination with the seq.*.local() functions.
So, you cannot use seq.read.local() on a file that was opened with seq.open().
Return values
>=0 success
<0 error; probably lfn not connected
Context
ttdllbw library function.
Syntax
long seq.write.local( string buf, long size, long lfn )
Description
This writes data from the specified buffer to the specified file, beginning at the current file position.
Functions reference
7-10
Client file access
Arguments
buf
The data that must be written to the file.
size
The number of bytes that must be written to the file.
lfn
The file pointer, as returned by seq.open.local() when the file was opened.
Note
You cannot use seq.*() functions in combination with the seq.*.local() functions.
So, you cannot use seq.write.local() on a file that was opened with seq.open().
Return values
>=0 success
<0 error; probably lfn not connected
Context
ttdllbw library function.
Syntax
long server2client( string source, string dest, long text.mode, [long progress.window] )
Description
This copies a specified file from the server to the client. The function supports long file names.
Arguments
source dest
The source file name, on the server.
The destination file name, on the client.
text.mode
This is a boolean value that specifies whether the file is to be copied in text or binary mode:
<>0 text mode
0 binary mode
Functions reference
7-11
Client file access
progress.
window
Use this optional argument to specify whether a progress indicator must be displayed to indicate the progress of the copy action:
<>0 progress indicator is displayed
0 progress indicator is not displayed
Notes
In order to use a progress indicator, you must first create it with
change its value. If you specify the PROGRESS.STOP and/or
PROGRESS.CANCEL modes when creating the indicator, the user can stop or cancel the copy operation before it has completed. In both cases, the destination file is deleted.
Return values
0
1
<0 success error; process canceled by the user error; source file not copied to the destination file
Example
server2client("C:\Program Files\Test.txt2", bse.tmp.dir$()
& "/test1.txt", false, false)
Context
ttdllbw library function.
Functions reference
7-12
Use the rgb() function to compose colors by specifying their red, green, and blue intensities. You can then use these colors, for example, when creating graphical objects such as windows, push buttons, labels, and so on. Use the other functions to retrieve the red, green, or blue intensity of an existing color.
On a monochrome display, colors are converted to fill patterns. On a 16-color display, the closest match to the composed color is used. Use get.display() to check the number of colors available on the display.
In addition to composing your own colors, you can use the following predefined colors:
RGB.BLACK
RGB.MAGENTA
RGB.RED
RGB.BLUE
RGB.GREEN
RGB.WHITE
RGB.YELLOW
RGB.GRAY
RGB.CYAN
long long long long blue.component
green.component
red.component
rgb
( long color )
( long color )
( long color )
( long red, long green, long blue)
Functions reference
8-1
Colors
Syntax
long blue.component( long color ) long green.component( long color ) long red.component( long color )
Description
These return the values of the blue, green, and red components respectively of an rgb color.
Context
3GL library function.
Example
long new_color, red_int, green_int, blue_int new_color = rgb(46,139,87) red_int = red.component( new_color ) | 46 green_int = green.component( new_color ) | 139 blue_int = blue.component( new_color ) | 87
Syntax
long rgb( long red, long green, long blue )
Description
Use this to compose a color by specifying its red, green, and blue intensities. The intensities must be in the range 0 to 255.
Return values
A long which can be used as a color in graphical contexts such as windows, user interface controls, and so on.
Context
3GL library function.
Functions reference
8-2
Example
long new_color, red_int, green_int, blue_int new_color = rgb(46,139,87) red_int = red.component( new_color ) | 46 green_int = green.component( new_color ) | 139 blue_int = blue.component( new_color ) | 87
Colors
Functions reference
8-3
Colors
Functions reference
8-4
Use these functions to switch to another company and to retrieve information about the current company.
long compnr.check
string get.company
long get.compnr
long switch.to.company
( long new_compnr )
( )
( )
( long new_compnr )
Syntax
long compnr.check( long new_compnr )
Description
This switches to another company and sets the read-only variable COMPNR to the specified company number. It checks whether the user is authorized for the new company, and switches company only if so.
Notes
makes heavier demands on system resources.
Be aware that when there is a switch to another company, the user’s first day of the week does not change, even if the new company has a different first day of the week. switch.to.company() returns an error value if the old and new companies have different first days of the week. compnr.check() does not.
Functions reference
9-1
Company operations
Super users are authorized for all company numbers. They always have authority to switch to a different company number. In addition, super users can use the data dictionary to authorize other users for particular company numbers.
Return values
TRUE (<>0) user is authorized; company switched
FALSE (0) user is not authorized; company not switched
Context
Bshell function.
Example
if ( not compnr.check(200) ) then message( "No permission to change to this company number" ) endif
Syntax
string get.company( )
Description
This returns the name of the current company.
Context
3GL library function.
Syntax
long get.compnr( )
Description
This returns the ID number of the current company.
Functions reference
9-2
Company operations
Context
Bshell function.
Syntax
long switch.to.company( long new_compnr )
Description
This switches to another company and sets the read-only variable COMPNR to the specified company number. It performs several checks before switching company and switches company only if the checks are successful. For example, it checks if the user is authorized to change to the new company, it checks if the package combination corresponds with the new company number, and it checks if the old and new companies have the same first day of the week.
Notes
makes heavier demands on system resources.
Be aware that when there is a switch to another company, the user’s first day of the week does not change, even if the new company has a different first day of the week. switch.to.company() returns an error value if the old and new companies have different first days of the week; compnr.check() does not.
Super users are authorized for all company numbers. They always have authority to switch to a different company number. In addition, super users can also use the data dictionary to authorize other users for particular company numbers.
Return values
1
-1
-2
-3
-4 success company not available no permission to change to this company package combination does not correspond with new company number first day of the week does not correspond to first day of the week of original company
Functions reference
9-3
Company operations
Context
3GL library function.
Functions reference
9-4
Use this function to create and fill the multicurrency table. Currency rotation is based on the order of currencies in this table.
void set.currencies
( long number.of.currency, string currency(3) )
Syntax
void set.currencies( long number.of.currency, string currency(3) )
Description
Use this function to create and fill the multicurrency table. The function inserts a single entry in the table. Currency rotation is based on the order of currencies in this table.
Context
4GL library function.
You can use this function only in 4GL scripts.
Example
set.currencies( 1, "HFL" ) set.currencies( 2, "USD" ) set.currencies( 3, "DEM" )
Functions reference
10-1
Currency tables
Functions reference
10-2
Use these functions for handling database input and output.
In BaanERP, the functions db.curr(), db.first(), db.last(), db.next(),
SELECT statements. They are supported for backward compatibility only. In new applications, use queries instead.
In BaanERP, certain 4GL functions have Data Access Layer (DAL) equivalents.
The following table lists these functions and their DAL equivalents.
on.main.table() on.old.occ() set.input.error() skip.io() abort.io() db.update() db.delete() db.insert() with.object.set.do() with.old.object.values.do() dal.set.error.message() return(DALHOOKERROR) dal.set.error.message() return(DALHOOKERROR) dal.set.error.message() return(DALHOOKERROR) dal.update() dal.destroy() dal.new()
If a DAL exists for a particular table, it is preferable to use the DAL functions.
The older functions access the database directly. When you make changes to the database with these functions, logic integrity checks programmed in the DAL are not executed. When you make changes to the database with the DAL functions, the relevant DAL hooks are executed automatically. This ensures the logic integrity of the database.
Functions reference
11-1
Database operations
For further information about database handling in general and about the Data
Access Layer, see Chapter 5, Database Handling, and Chapter 6, Data Access
Layer, in U7168A US BaanERP Tools: Programming Features.
The naming syntax for tables, record buffers, and fields is:
table tppmmmxxx
rcd.tppmmmxxx
ppmmmxxx.ffffffff
| table declaration
| record buffer of table
| logical field of table where t stands for table, pp is the package code, mmm is the module code, xxx is the table number, and ffffffff is a field name.
If a table is used in a script, it must be declared with the statement: table tppmmmxxx
Declaration of a table implies declaration of all its fields and its record buffer.
These do not need to be declared separately.
There are no functions for opening or closing a table. A table is automatically opened the first time it is accessed. It is automatically closed when the program ends.
In BaanERP, there are two main categories of errors: operating system errors and database system errors. For an explanation of the error codes, consult your operating system or database system documentation, or see Chapter 10, Errors, in
U7168A US BaanERP Tools: Programming Features.
Normally, a program can detect only four of the database errors: EDUPL,
EENDFILE, ENOREC, and EROWCHANGED. When other errors occur, an error message is displayed on screen. However, you can use the predefined variable error.bypass to suppress error messages and enable a program to detect some or all errors instead.
Functions reference
11-2
Database operations
This variable can have the following values:
0 This is the default value. The program can detect the following database errors: EDUPL, EENDFILE, ENOREC, and EROWCHANGED.
Some fatal errors cause a direct abort of the application. When this happens, the message ’Cannot continue’ is displayed.
If you attempt to lock a record or table that is already locked by another process, the program returns to the retry point automatically a number of times (by default, 10 times) before stopping the session and displaying the error message.
1 The program can detect all errors. So no database error messages are displayed on screen.
A program can detect database errors in the following ways: n
Test return values. For example: if db.insert( tpctst999 ) = EENDFILE then ...
n
Use db.error(). For example: db.insert( tpctst999 ) if db.error( tpctst999 ) = EENDFILE then ...
n
Use the predefined variable e. For example: db.insert( tpctst999 ) if e = EENDFILE then ...
n
The ENDSELECT and SELECTEMPTY statements automatically detect the
EENDFILE and ENOREC errors respectively.
Functions reference
11-3
Database operations
void long void long void long void void void void long long long long long long long long abort.io
abort.transaction
activate.search
commit.transaction
dal.destroy
dal.get.property.
flag dal.new
( string mesg(14) [, ...] )
( )
( )
( )
( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]])
( string class_name, long object_set, string prop_name)
( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]]) dal.set.property
dal.start.business.
method dal.update
db.bind
( string class_name, long object_set, const string prop_name, value, long mode)
( long|string set_id, string name, ref long retval [, arg]... )
( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]] )
( string table_name(9) [, ref string buffer(.) [, long comp_nr]] ) db.change.order
db.check.restricted
( long table_id, long index_nr
[, long comp_nr] )
( long table_id, long mode, ref string message(256) )
( long table_id ) db.check.row.
changed db.check.row.domains
( long table_id, ref string fld_name(18) ) db.clear.table
( long table_id[, long flag
[, long comp_nr]] ) db.columns.to.record
( long table_id ) db.create.table
( long table_id [, long comp_nr] )
Functions reference
11-4
Database operations
long long long long long long long void long long long long long long long long long long db.curr
db.delete
db.drop.table
long long db.eq
db.error
string db.error.message
long db.first
long long long db.ge
db.gt
db.indexinfo
db.insert
db.last
db.le
db.lock.table
db.lt
db.next
db.nr.indices
db.nr.rows
db.permission
db.prev
db.record.to.
columns db.ref.handle.mode
db.retry.hit
db.retry.point
db.row.length
( long table_id [, long lock])
( long table_id [, long mode
[, long eflag]] )
( long table_id [, long ignore_refs, long comp_nr] )
( long table_id [, long lock])
( [long table_id] )
( )
( long table_id [, long lock])
( long table_id [, long lock])
( long table_id [, long lock])
( long table_id, long index_nr, ref long index_info(32,3), ref long indexparts, ref long indexdups, ref long indexactive )
( long table_id [, long mode
[, long eflag]] )
( long table_id [, long lock]
)
( long table_id [, long lock])
( long table_id [, long comp_nr] )
( long table_id [, long lock])
( long table_id [, long lock]
( long table_id, ref long nr_indices)
( long table_id, ref long nr_rows [, long comp_nr] )
( long table_id [, string field(18)
[, ref string buffer(.)]] )
( long table_id [, long lock])
( long table_id )
( string table_name(9), long mode )
( )
( )
( long table_id, ref long row_length)
Functions reference
11-5
Database operations
void void void void void void long long long void void void long db.set.to.default
db.unbind
db.update
on.main.table
restore.rcd.main
set.limits.off
set.transaction.
readonly skip.io
store.occ.max
store.occ.min
to.key
with.object.set.do
with.old.object.
values.do
( long table_id )
( long table_id )
( long table_id [, long mode
[, long eflag]] )
( function_name [, ...] )
( long occurrence )
( )
( )
( string mesg(14) [, ...] )
( )
( )
( long key_number )
( string function_name, argument1, argument2, ... )
( string function_name, argument1, argument2, ... )
Syntax
void abort.io( string mesg(14) [, ...] )
Description
This cancels the current database transaction.
After this function is called, new values entered on the form remain on the form and the predefined variable stp.abort.error is set to TRUE.
In the case of a single-occurrence form, the transaction is then canceled without further actions. In the case of a multioccurrence form, the transaction is canceled but the user is given the opportunity to retry the updates that did not cause an error. If the user chooses to retry the updates, occurrences that caused an error are skipped and those that did not are updated. If the user chooses not to retry the transaction, the transaction is canceled without further action. The user can then start the update again or recover.
Functions reference
11-6
Database operations
Arguments
mesg
This specifies a message defined in the data dictionary. The message is displayed on screen when abort.io() is called. If you specify an empty string here, the standard program displays a default message.
The argument can contain substitution symbols such as
%d
or
%s
(see
second, third, etc. arguments of the function. The number of arguments is variable.
Note
DALHOOKERROR is returned by, for example, a before.save.object() or
Context
4GL library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections (but not in programs of type 4): before.write, before.rewrite, before.delete
after.write, after.rewrite, after.delete
after.skip.write, after.skip.rewrite, after.skip.delete
after.choice of choice.update.db
Example
main.table.io: before.rewrite: select tiitm001.* from tiitm001 for update where tiitm001.item between :item.f and :item.t
selectdo tiitm001.cwar = "002" db.update(ttiitm001, DB.RETRY) selecterror abort.io("pctsts0010", tiitm001.item)
| transaction canceled on item %s endselect
Functions reference
11-7
Database operations
Syntax
long abort.transaction()
Description
This cancels the current database transaction. No changes are stored in the database.
To commit a transaction and store changes made in the database, use
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
void activate.search()
Description
This forces a random search action on the main table. You call the function immediately after input to a field during insertion of a new record (standard command ADD.SET or DUPL.OCCUR) or during MODIFY.SET (if the predefined variable modify.prim.key is set to TRUE).
When a new record is being added to the database, the standard program normally executes a search action in the main table after input to the field(s) of the primary index. If the key values entered belong to an existing record in the main table, the standard program displays all the fields of that record and stops adding the new record. Otherwise, the user must fill the remaining fields; then the record is added to the main table.
Functions reference
11-8
Database operations
In some applications, not all parts of the primary index appear on the form. In this case, the search operation in the main table occurs when the user leaves the last input field of the occurrence. You can force an earlier search action by calling activate.search() after input to any field of the occurrence.
Context
Bshell function.
You can use this function only in the 4GL event subsection on.input. You cannot use it in programs of type 4.
Example
| Suppose there are 2 input fields on the form, ’number’
| and ’name’, which are not parts of the primary index of
| the main table. When the user leaves the field ’number’,
| a search action in the main table should be done by the
| standard program: field.number: on.input: activate.search()
Syntax
long commit.transaction()
Description
This ends the current transaction. All changes made during the transaction are stored in the database.
To cancel a transaction, use abort.transaction() instead.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-9
Database operations
Syntax
void dal.destroy( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]] )
Description
Use this to delete a database record. The function encapsulates the db.delete() function with the DAL hooks of the object set. If the before.destroy.object() hook fails, the database operation is cancelled.
Arguments
class_name
A string containing the name of the DAL.
object_set
The ID of an open object set (if this ID is not known, use the table ID).
retval
The return value of the object hooks (<0), of the db.delete() function (>0), or 0 if the function is successful.
prop_check
A boolean value that indicates whether or not property checks must be executed. If set to TRUE, the property checks are executed immediately before the before.destroy.object() hook.
If set to FALSE, the property checks are not executed.
mode eflag
Set this to DB.RETRY if retry points and the SELECT FOR
UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See the “Error handling” section in Chapter 5, Database handling, in
U7168A US BaanERP
Tools: Programming Features.
Context
DAL function.
Functions reference
11-10
Database operations
Syntax
long dal.get.property.flag( string class_name, long object_set, string prop_name )
Description
Use this to retrieve the value of the has_changed flag (see “Property hooks” in
Chapter 6 in U7168A US BaanERP Tools: Programming Features) for any database property. The property must have been changed by the
You can call this function from both UI and DAL scripts.
Arguments
class_name
A string containing the name of the DAL.
object_set
The ID of an open object set (if this ID is not known, use the table ID).
prop_name
A string containing the name of the field for which the has_changed value must be returned.
Return values
The function returns the value of the has_changed flag of the specified property.
The possible values are:
0
DAL_NEW property not changed change caused by inserting a new object
DAL_UPDATE change caused by updating an existing object
Properties with no check function in the DAL always return 0.
Context
DAL function.
Functions reference
11-11
Database operations
Example
This function is programmed in DAL tdsls401.
function extern long tdsls401.oqua.check(long has_changed)
{ if tdsls400.stat = tdsls.stat.invoiced then if has_changed or dal.get.property.flag("tdsls401", ttdsls401,
"tdsls401.pric") then dal.set.error.message("tdsls44042")
| You cannot change quantity or price, because
| the order is already invoiced return(DALHOOKERROR) endif else if tdsls401.oqua > tdsls401.comq then endif endif
. . .
return(0) dal.set.error.message(tdsls44043)
| Order quantity may not exceed committed
| quantity return(DALHOOKERROR)
}
Syntax
void dal.new( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]])
Description
Use this to add a new record to the database. The function encapsulates the
Arguments
class_name
A string containing the name of the DAL.
object_set
The ID of an open object set (if this ID is not known, use the table ID).
Functions reference
11-12
Database operations
retval prop_check
A boolean value that indicates whether or not property checks must be executed. If set to TRUE, the property checks are executed immediately before the before.save.object() hook. If set to FALSE, the property checks are not executed.
mode
The return value of the object hooks (<0), of the db.insert() function (> 0), or 0 if the function is successful.
Set this to DB.RETRY if retry points and the SELECT FOR
UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag
For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See the “Error handling” section in Chapter 5, Database handling, in
U7168A US BaanERP
Tools: Programming Features.
Context
DAL function.
Syntax
long dal.set.property( string class_name, long object_set, const string prop_name, value, long mode )
Description
In order to notify the DAL about a change to the value of a property, you must use this function to change the value. Using this function ensures that the relevant property hooks are executed when the value is changed. If you use an assignment or the db.* functions to change a property value, the DAL is not notified of the change. Consequently, the property checks in the DAL are not executed.
You can call this function from both UI and DAL scripts.
Functions reference
11-13
Database operations
Arguments
class_name
A string containing the name of the DAL.
object_set
The ID of an open object set (if this ID is not known, use the table ID).
prop_name
The name of the property whose value must be changed.
mode
Use this to indicate the value for the has_changed flag of the property. The possible values are DAL_NEW or DAL_UPDATE.
Return values
The return value of the property check.
Context
DAL function.
Example
This is an example of using the function in a DAL script to update an object in another object set.
| This function is in the DAL of tdsls401 function extern long after.update.object(long mode)
{ long ret
} if mode = DAL_NEW then old.amnt = 0 endif select tdsls400.* from tdsls400 for update where tdsls400.orno =:tdsls401.orno
selectdo dal.set.property("tdsls400", ttdsls400, "tdsls400.amnt", tdsls400.amnt - old.amnt + tdsls401.amnt,
DAL_UPDATE) dal.update("tdsls400", ttdsls400, ret, true, db.retry) endselect return(ret)
Functions reference
11-14
Database operations
Syntax
void dal.start.business.method( long|string set_id, string name, ref long retval [, arg]... )
Description
This starts a specified business method.
The business method must be implemented as a function of type EXTERN
LONG. If this is the first call to a particular class (that is, table), the
is called.
Arguments
set_id
Indicates the name of the DAL that implements the business method.
The set_id argument can be a long (use in external programs) or a string (use in UI scripts).
name
The name of the business method.
retval
The return value.
Negative values are reserved for the calling mechanism. For example:
-1
-2
DALNOOBJSET
DALNOMETHOD
The business method may return only DALHOOKERROR, 0, or positive numbers.
arg
Use these optional arguments to pass arguments to the business method.
Context
DAL function.
Functions reference
11-15
Database operations
Example
dal.start.business.method("cfcmd100", "print.object.set", feature.f, feature.t) function extern long print.object.set( domain cfcmd.feat
feature.f, domain cfcmd.feat
feature.t),
{ domain dcbool show.pi
show.pi = tcmcs.dll0011.show.progress.indicator() if show.pi then init.progress.indicator(feature.f, feature.t) endif
} select cfcmd100.* from cfcmd100 where cfcmd100.feat inrange :feature.f and :feature.t
order by cfcmd100._index1
selectdo if show.pi then
|* calculate progress percentage prgi.val = prgi.val + prgi.stp
if prgi.tot > 0 then prgi.prc = (prgi.val / prgi.tot) * 100 endif if change.progress.indicator(prgi.prc) then
|* user pressed cancel/stop button return(0) endif endif prnt.data = "cfcmd110" print.record(1) endselect return(0)
Functions reference
11-16
Database operations
Syntax
void dal.update( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]] )
Description
Use this to update an existing database record. The function encapsulates the
Arguments
class_name
A string containing the name of the DAL.
object_set
The ID of an open object set (if this ID is not known, use the table ID).
retval
The return value of the object hooks (<0), of the db.insert() function (>0), or 0 if the function is successful.
prop_check
A boolean value that indicates whether or not property checks must be executed. If set to TRUE, the property checks are executed immediately before the before.save.object() hook. If set to FALSE, the property checks are not executed.
mode eflag
Set this to DB.RETRY if retry points and the SELECT FOR
UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See the “Error handling” section in Chapter 5, Database handling, in
U7168A US BaanERP
Tools: Programming Features.
Context
DAL function.
Functions reference
11-17
Database operations
Syntax
long db.bind( string table_name(9) [, ref string buffer(.)
[, long comp_nr]] )
Description
This creates a pointer to a specified table. It returns a table ID that you use in other database calls to identify the table. The pointer is to a table with a particular company number and record buffer. You can create additional pointers to the same table by calling the function with a different company number and/or record buffer.
Arguments
table_name
The table name.
buffer
This optional argument specifies the record buffer to be used for the table. If you omit this argument, or if you specify an empty string, the default record buffer is used (that is, rcd.tppmmmxxx
).
comp_nr
This optional argument specifies a company number for the table. The default company is the company of the user. If you include this argument, you must also include the buffer argument. So, if you want to specify a company other than the default company but want to use the default record buffer, specify the default buffer or an empty string in the buffer argument.
Note
When you create more than one pointer to a table, you must use a different record buffer for each one.
Return values
>0 success; pointer is returned
0 error
Context
Bshell function.
Functions reference
11-18
Database operations
Example
long tcmcs001_id if (switch.to.company(200) > 0) then tcmcs001_id = db.bind("ttcmcs001") db.first(ttcmcs001_id) endif
...
db.first(ttcmcs001)
Syntax
long db.change.order( long table_id, long index_nr [, long comp_nr] )
Description
This makes a specified index the current index. After this action, the record pointer is undefined.
Arguments
table_id
The table ID, as returned by db.bind().
index_nr
The number of the index that you want to become the current index. The index must exist.
comp_nr
This optional argument specifies a company number for the table.
The default company is the company of the user.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-19
Database operations
Syntax
long db.check.restricted( long table_id, long mode, ref string message(256) )
Description
In a table definition, it is possible to set restrictions on update and/or delete actions for records that are referenced by other tables. These restrictions mean that you cannot delete and/or update the primary key that is referenced by another table. This function checks whether there are references to the current record with delete and/or update restrictions. This function can take a long time to complete if no reference counter is kept (lookup mode).
Arguments
table_id
The table ID, as returned by db.bind().
mode
1
2
Use to specify whether you want to check for delete or update restrictions. Possible values are: delete mode update mode
message
This returns the reference message of the table. This message is defined in the data dictionary.
Return values
0
1
-1 no reference found one or more references found error
Context
Bshell function.
Functions reference
11-20
Database operations
Syntax
long db.check.row.changed( long table_id )
Description
This checks whether a record that has been locked with a delayed lock has yet been changed.
Arguments
table_id
The table ID, as returned by db.bind().
Return values
0
<>0 record has not been changed error
EROWCHANGED record has been changed
Context
Bshell function.
Syntax
long db.check.row.domains( long table_id, ref string fld_name(18) )
Description
This checks whether the current record of a specified table conforms to the domain definitions in the data dictionary. All fields of the record are checked in turn until an error occurs. The function returns when the first error is encountered.
Arguments
table_id
The table ID, as returned by db.bind().
fld_name
This returns the name of the first incorrect field.
Functions reference
11-21
Database operations
Return values
0
-1 no errors invalid table ID
ENOTINRANGE error in a field
If an error is returned, you can retrieve information about the specific error using
Context
Bshell function.
Syntax
long db.clear.table( long table_id [, long flag [, long comp_nr]] )
Description
This deletes all data from a specified table. Reference counters are automatically updated.
By default, all deleted records are saved in rollback segments. Consequently, using this function to clear a large table can result in reduced performance and, in some cases, can cause overflow of the internal rollback segments.
Functions reference
11-22
Database operations
Arguments
table_id flag
The table ID, as returned by db.bind().
Use this optional argument to indicate whether the delete operation must be performed as a single transaction or as multiple transactions. The possible values are:
0 WITH.ROLLBACK
The table is cleared in a single transaction. All records are saved in rollback segments. This is the default option.
1 NO.ROLLBACK
The table is cleared in one or more transactions, depending on the number of records in the table. Each transaction is automatically committed after 20 records have been deleted. The number of records deleted in the final transaction can be 20 or less; this depends on how many records remain to be deleted.
When you use this option, transactions are small and records are not saved in rollback segments.
When you use this option, you must place db.clear.table() at the start of the transaction.
comp_nr
This optional argument specifies a company number for the table.
The default company is the company of the user.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-23
Database operations
Syntax
long db.columns.to.record( long table_id )
Description
The record buffer of a table is used for reading records from that table. When you bind to a table (see db.bind()) and specify that the default record buffer is to be used, the contents of the table fields are automatically copied to the buffer. This does not happen when you specify a record buffer other than the default buffer.
Consequently, you must call this function to copy the field values to the buffer if you have filled the fields before reading from the database.
Arguments
table_id
The table ID, as returned by db.bind().
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.create.table( table table_name [, long comp_nr] )
Description
This creates a new database table.
Arguments
table_name
The name for the new table.
comp_nr
This optional argument specifies a company number for the table. The default company is the company of the user.
Functions reference
11-24
Database operations
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.curr( long table_id [, long lock] )
Description
This reads the current record from a specified table.
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-25
Database operations
Syntax
long db.delete( long table_id [, long mode [, long eflag]])
Description
This deletes the current record. The record pointer is not changed, so the current record is undefined after the record has been deleted.
Arguments
table_id
The table ID, as returned by db.bind().
mode
Set this to DB.RETRY if retry points and the SELECT FOR
UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag
For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See the “Error handling” section in Chapter 5,
Database handling, in
U7168A US BaanERP Tools: Programming
Features.
Return values
0 success
>0 error
Context
Bshell function.
Syntax
long db.drop.table( long table_id [, long ignore_refs] [, long comp_nr] )
Description
This deletes a specified table. Data and indices associated with the table are also deleted. Reference counters are automatically updated.
Functions reference
11-26
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
ignore_refs
If you set this optional argument to DB.IGNORE.ALL.REFS, the data is deleted regardless of whether it is referenced by other tables.
comp_nr
This optional argument specifies a company number for the table. The default company is the company of the user.
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.eq( long table_id [, long lock] )
Description
This reads from a specified table the record whose key value equals a certain predefined value. Before calling db.eq(), you must assign the required value to the key field.
For example, the following code retrieves the item with item number 001 from the items table: tiitm001.item = "001" db.eq( ttiitm001 )
Functions reference
11-27
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.error( [long table_id] )
Description
Use this to retrieve the error code returned by the most recent database action. If you specify a table ID, the function retrieves the most recent error code returned by an action on that table.
Context
Bshell function.
Functions reference
11-28
Database operations
Syntax
string db.error.message()
Description
Some errors returned by a database action have an associated error message. This message provides additional information about the error. Use the
with the most recent error code returned by a database action.
Return values
The error message associated with the most recent error that occurred. Or an empty string if no message is associated with the error.
Context
Bshell function.
Syntax
long db.first( long table_id [, long lock] )
Description
This reads the first record from a specified table. It uses the current index to search the table.
Functions reference
11-29
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. the pssible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.ge( long table_id [, long lock] )
Description
This reads from a specified table the record whose key value is greater than or equal to a certain predefined value. Before calling db.ge(), you must assign the required value to the key field. For example: tiitm001.item = "001" db.ge( ttiitm001 )
Functions reference
11-30
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.gt( long table_id [, long lock] )
Description
This reads from a specified table the record whose key value is greater than a certain predefined value. Before calling db.gt(), you must assign the required value to the key field. For example: tiitm001.item = "001" db.gt( ttiitm001 )
Functions reference
11-31
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.indexinfo( long table_id, long index_nr, ref long index_info(32,3), ref long indexparts, ref long indexdups, ref long indexactive )
Description
This returns information about the parts of a specified index.
Functions reference
11-32
Database operations
Arguments
table_id index_nr index_info
The table ID, as returned by db.bind().
The index number.
This returns the start position, length, and type of the index parts
(up to a maximum of 32 parts): index_info(i,1) Start position in the logical record of part i of the index.
index_info(i,2) Length of part i.
index_info(i,3) Type of part i. The possible values are:
DB.BYTE
DB.TIME
DB.INTEGER
DB.TEXT
DB.LONG
DB.MAIL
DB.DOUBLE
DB.BITSET
DB.STRING
DB.COMBINED
DB.DATE
DB.MULTIBYTE
indexparts indexups
Returns the number of parts in the index.
Indicates whether or not duplicate values are permitted.
indexactive
Indicates whether or not the index is active.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-33
Database operations
Syntax
long db.insert( long table_id [, long mode [, long eflag]])
Description
This adds a new record to a specified table. The record pointer does not change.
Arguments
table_id
The table ID, as returned by db.bind().
mode
Set this to DB.RETRY if retry points and the SELECT FOR
UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag
For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See the “Error handling” section in Chapter
5, Database handling, in
U7168A US BaanERP Tools:
Programming Features.
Return values
0 success
>0 error
Context
Bshell function.
Syntax
long db.last( long table_id [, long lock] )
Description
This reads the last record from a specified table. It uses the current index to search the table.
Functions reference
11-34
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.le( long table_id [, long lock] )
This reads from a specified table the record whose key value is less than or equal to a certain predefined value. Before calling db.le(), you must assign the required value to the key field. For example: tiitm001.item = "001" db.le( ttiitm001 )
Functions reference
11-35
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.lock.table( long table_id )
Description
This locks a specified table. Other users cannot then write to or delete the table or any parts of the table. Nor can they lock the table or any parts of the table. The lock is released by commit.transaction() or abort.transaction().
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-36
Database operations
Syntax
long db.lt( long table_id [, long lock] )
Description
This reads from a specified table the record whose key value is less than a certain predefined value. Before calling db.lt(), you must assign the required value to the key field. For example: tiitm001.item = "001" db.lt( ttiitm001 )
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.next( long table_id [, long lock] )
This reads the next record from a specified table. It uses the current index to search the table. If there is no current record, the function returns an error message.
Functions reference
11-37
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.nr.indices( long table_id, ref long nr_indices )
Description
This returns the number of indices that exist on a specified table.
Arguments
table_id
The table ID, as returned by db.bind().
nr_indices
Returns the number of indices on the table.
Return values
0 success
<>0 error
Functions reference
11-38
Database operations
Context
Bshell function.
Syntax
long db.nr.rows( long table_id, ref long nr_rows [, long comp_nr] )
Description
This returns the number of rows that a specified table contains.
Arguments
table_id nr_rows
The table ID, as returned by db.bind().
Returns the number of rows in the table.
comp_nr
This optional argument specifies a company number for the table.
The default company is the company of the user.
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.permission( long table_id [, string field(18) [, ref string buffer(.)]] )
Description
Use this to check the access permissions that a user has to a specified table or table field.
Functions reference
11-39
Database operations
Arguments
table_id
The table ID, as returned by db.bind().
field
To check the permissions for a particular field, enter the field name here. If you do not specify a field here, or if you specify an empty string, the function returns the permissions for the table.
buffer
A user’s permissions for a table or table field can depend on the contents of a record. In this case, you must specify the record buffer of the table in the buffer argument. The function returns the user’s permissions for the record in the record buffer. If a user’s permissions depend on the contents of a record, and you do not specify the buffer argument, the function returns
PERM.UNKNOWN.
Return values
The function returns a long that indicates the permissions that the user has on the table or on a specified field of that table. The return value consists of one of, or a combination of, the following codes:
NO.PERMISSION
PERM.READ
PERM.MODIFY
PERM.WRITE
PERM.DELETE
NO.RESTRICTION
4
8
1
2
16
(PERM.READ+PERM.MODIFY+PERM.WRITE+
PERM.DELETE)
32 PERM.UNKNOWN
So, if the value 6 is returned, the user is permitted to both read and modify the specified table or table field.
Context
Bshell function.
Functions reference
11-40
Database operations
Example
long p string buffer(18) if attr.permission = PERM.UNKNOWN then p = db.permission(ttccom001, "", buffer) else p = attr.permission
endif if p > PERM.READ then
....
else
| modifications not allowed in table tccom001 for
| this user endif
Syntax
long db.prev( long table_id [, long lock] )
Description
This reads the previous record from a specified table. It uses the current index to search the table. If there is no current record, the function returns an error message.
Arguments
table_id
The table ID, as returned by db.bind().
lock
By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are:
DB.LOCK
lock record for update
DB.DELAYED.LOCK
apply a delayed lock to the record; the lock is applied immediately before the update action
Functions reference
11-41
Database operations
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.record.to.columns( long table_id )
Description
When you bind to a table (see db.bind()) and specify that the default record buffer is to be used, the contents of the buffer are automatically copied to the table fields in your program script. This does not happen when you specify a record buffer other than the default buffer. Consequently, you must call this function to copy the field values from the buffer to the table fields in your program script.
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.ref.handle.mode( string table_name(9), long mode )
Description
Use this to check whether a full table scan (FTS) is necessary during delete or update operations. Delete and update operations can take a long time to complete when the table is referenced by other tables but no reference counter is kept
Functions reference
11-42
Database operations
(cascade, nullify, or lookup mode). When there is no index on the foreign key in the child table, normally a full table scan is required to search for referring records.
Arguments
table_name
The table name, without the leading ’t’ character.
mode
Possible modes:
DB.REF.UPDATE
DB.REF.DELETE
Return values
0
1 full table scan is not necessary full table scan is necessary
Context
Bshell function.
Syntax
long db.retry.hit()
Description
Use this to check whether the client database layer has returned to a retry point.
You must set the retry point by using db.retry.point() before you call
Tools: Programming Features.
Return values
0 retry point defined but not returned to
<>0 system returned to retry point
Context
Bshell function.
Functions reference
11-43
Database operations
Syntax
void db.retry.point()
Description
This sets a retry point for the current transaction. The program returns to this point if an error occurs during the transaction; the transaction is then retried.
When you include a retry point for a transaction, you must set it before the start of the transaction.
Context
Bshell function.
Syntax
long db.row.length( long table_id, ref long row_length )
Description
Use this to retrieve the length of records in a specified table.
Arguments
table_id
The table ID, as returned by db.bind().
row_length
This returns the number of bytes in a record of the specified table.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
11-44
Database operations
Syntax
long db.set.to.default( long table_id )
Description
This sets bound variables in the program script to the default values defined in the data dictionary.
Arguments
table_id
The table ID, as returned by db.bind().
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long db.unbind( long table_id )
Description
This deletes the specified table pointer.
Arguments
table_id
The table pointer, as returned by db.bind().
Return values
0 success
<>0 error
Functions reference
11-45
Database operations
Context
Bshell function.
Syntax
long db.update( long table_id [, long mode [, long eflag]])
Description
This rewrites the current record. When updating a record with this function, you are permitted to update the primary key of the record.
Arguments
table_id mode eflag
The table ID, as returned by db.bind().
This has two possible values:
DB.RETRY
Set this value if retry points and the
SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
DB.DELAYED.LOCK This option is available only for records for which a delayed lock has been set with db.eq().
For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See the “Error handling” section in
Chapter 5, Database handling, in
U7168A US BaanERP Tools:
Programming Features.
Return values
0 success
>0 error
Context
Bshell function.
Functions reference
11-46
Database operations
Syntax
void on.main.table( function_name [, ...] )
Description
This copies the contents current record of the main table to the record buffer of that table, saves the record, and executes the specified function. After that the saved record buffer is restored. This enables you to perform actions on the record contents without affecting the values in the table.
Arguments
function_name
The name of the function that must be executed. The function must be of type void.
. . .
Use these optional arguments to pass one or more arguments to the function.
Context
4GL library function.
You can use this function only in 4GL scripts. You cannot use it in the
point. The function is not relevant to programs of type 4.
In DAL scripts, with.object.set.do() is the equivalent of on.main.table().
Example
| Suppose you have a table to which you can add numbers only
| if a certain value is present in the main table declaration: long go_ahead field.pctst999.number: check.input: on.main.table( check_number, 5 ) if not go_ahead then set.input.error("pctst0003", 5) |"Number %d not
| present" endif
Functions reference
11-47
Database operations
functions: function void check_number( long number )
{ select pctst999.* from pctst999 where pctst999.number = :number as set with 1 rows selectdo go_ahead = TRUE selectempty go_ahead = FALSE endselect return
}
Syntax
void restore.rcd.main( long occurrence )
Description
This updates the main table with the contents of the buffer of the specified occurrence. It also makes the specified occurrence the current occurrence.
Arguments
occurrence
The occurrence number.
Context
4GL library function.
You can use this function only in 4GL scripts. You cannot use the function in
Functions reference
11-48
Database operations
Syntax
void set.limits.off()
Description
This removes the limits set with the store.occ.max() and/or store.occ.min() functions. The entire table can then be accessed again.
Context
4GL library function.
You can use this function only in 4GL scripts. You cannot use the function in
Syntax
long set.transaction.readonly()
Description
This defines a transaction as read only, with read consistency. The transaction can only read records (without locks) from the database; it cannot update the database. Read consistency is retained during the entire transaction. That is, your view of the database does not change even when the database is updated by other users.
When included, this function must be the first command of a transaction. So, you must include it either at the start of the program or immediately following a
Because it is not possible to update the database in a read-only transaction, you can use only the following database calls in the transaction: db.first() db.last() db.next() db.prev() db.gt() db.ge() db.eq() db.lt() db.le() db.set.to.default() db.change.order() db.indexinfo() db.nr.indices() db.nr.rows()
Functions reference
11-49
Database operations
db.cur() db.bind() db.unbind() db.error()
Context
Bshell function.
db.row.length() db.record.to.columns() db.columns.to.record()
Syntax
void skip.io( string mesg(14) [, ...] )
Description
Use this to skip the current database action on the current record. The predefined variable stp.skip.error indicates whether or not skip.io() has been called.
Arguments
mesg
This specifies a message that is defined in the data dictionary. This message is displayed on screen when you call skip.io(). If you specify an empty string, the standard program displays a default message.
The message can contain substitution symbols such as
%d
or
%s
(see
second, third, etc. arguments of the function. The number of arguments is variable.
Note
For performance reasons, it is preferable to use query.extend.where() instead of
Context
4GL library function.
You can use this function only in 4GL scripts. You cannot use it in programs of type 4. You can use it in the following event subsections: after.read, read.view, before.write, before.rewrite, before.delete
Functions reference
11-50
Database operations
Example
main.table.io: before.delete: if pctst999.number = 0 then endif skip.io("pctsts0010")
| record with number zero may not be deleted
Syntax
void store.occ.max() void store.occ.min()
Description
Normally, standard commands that access records of the main table can access all records of that table. You can use these functions to limit the records that can be accessed to those whose key values are within a specified range. Use
define the lower limit of the range. If you wish, you can define only a maximum or only a minimum limit.
Before you call either of these functions, you must fill the key value with the required maximum or minimum value. If you set a limit that has previously been defined, the new value of the limit overwrites the previous value of the limit.
Use set.limits.off() to switch off the limits defined with these functions.
Note
For performance reasons, it is preferable to use query.extend.where() instead of these functions.
Context
4GL library functions.
You can use these functions only in 4GL scripts. You cannot use them in programs of type 4 or in before.program sections.
Functions reference
11-51
Database operations
Examples
Example 1
| Suppose that on the first form you can access the entire
| main table while on the second form you can access only
| records in the range 20 to 100 form.2: before.form: pctst999.number = 20 | Fill minimum key value store.occ.min() | Set minimum pctst999.number = 100 | Fill maximum key value store.occ.max() | Set maximum after.form: set.limits.off()
Example 2
before.form: tibom010.mitm = "X" set.min(tibom010.pono) store.occ.min() set.max(tibom010.pono) store.occ.max() after.form: set.limits.off()
Syntax
void to.key( long key_number )
Description
Use this to change the key of the main table without user interaction. The
key_number argument specifies the new key.
When changing the key of the main table within the on.main.table() function, you must use db.change.order() instead. Also, to change the key of a table other than the main table, you must use db.change.order().
You can also use execute(change.order)
to change the key of the main table. In this case, the user selects the new key.
Functions reference
11-52
Database operations
Note that during execution of the ADD.SET, MODIFY.SET and
MARK.DELETE commands, the current key is saved and the primary key becomes the current key. After the database has been updated, the standard program restores the saved key.
Context
4GL library function.
You can use these functions only in 4GL scripts and only in programs of type 1,
2, and 3. You can use the function in the following event subsections: on.choice, after.choice
init.form, before.form, after.form
on.entry
Syntax
void with.object.set.do( string function_name, argument1, argument2, ... )
Description
This copies the contents of the current record of the main table to the record buffer of that table, saves the record, and executes the specified function. After that the saved record buffer is restored. This enables you to perform actions on the record contents without affecting the values in the table.
You can call this function in any DAL hook. It is the equivalent of the
Arguments
function_name
The name of the function that must be executed. The function must be of type void.
argument1, . . .
Use these optional arguments to pass one or more arguments to the function.
Context
DAL function.
Functions reference
11-53
Database operations
Syntax
void with.old.object.values.do( string function_name, argument1, argument2, ... )
Description
This executes the specified function for the current occurrence, using the old values of the record. The record must have been previously modified.
You can call this function in the before.save.object() hook of a DAL script. It is the equivalent of the on.old.occ() function used in UI scripts.
Arguments
function_name
The name of the function that must be executed. The function must be of type void.
argument1, ...
Use these optional arguments to pass one or more arguments to the specified function.
Context
DAL function.
Functions reference
11-54
Use these functions to manipulate dates, times, and time zones.
BaanERP provides time-zone independent date and time support. The user interface always shows local dates and times. Internally, however, BaanERP stores dates and times in Universal Coordinated Time (UTC). It stores both date and time in a single long integer referred to as the UTC long format. This integer represents the number of seconds since 0:00 hour, January 1, 1970 (in UTC). The use of a long integer imposes an upper date limit of 2038.
The UTC functions described in this section support conversion between local dates and times and UTC. Users can set their local time zone via the user interface. 3GL/4GL programs can modify the time zone at runtime using various time zone functions.
BaanERP handles week numbering according to ISO:5601. Week 01 is the week that includes the first Thursday of the year or January 4 th
. Monday is the first day of the week (that is, day 1). Sunday is the last day of the week (that is, day 7).
In the company-data settings in the data dictionary it is possible to define the first day of the week (that is, day 01) for individual BaanERP users. If a user’s first day of the week is Monday, then week numbering follows the ISO standard.
However, if a user’s first day of the week is other than Monday (Sunday or
Wednesday, for example), the week number is calculated differently. The week number is always the ISO week number of the Monday that occurs in the user’s week.
Functions reference
12-1
Dates, times, time zones
The following diagram illustrates this:
In the example, the user’s first day of the week is a Wednesday. The week number of the week beginning Wednesday 9 th and ending Tuesday 15 th
is the
ISO week number for the Monday that occurs in that week. The ISO week number of Monday 14 th
is week 6, so Wednesday 9 th
to Tuesday 15 th
is week 6.
Note
For an explanation of date and time formats, see Chapter 20, Formatting output.
Local dates/times
long string long date.num
date.to.
inputstr$ date.to.num
string long long dte$ inputstr.to.
date num.to.date
string long num.to.date$ num.to.week
( )
( long dayno, string format(7), long length )
( long yearno, long monthno, long month_dayno )
( )
( string inputstr(.), string format(7))
( long dayno, ref long yearno, ref long monthno, ref long month_dayno)
( long dayno, long mode )
( long dayno, ref long week_dayno, ref long year_dayno, ref long weekno [, ref long yearno] )
Functions reference
12-2
Dates, times, time zones
long long time.num
week.to.num
( )
( long weekno, long yearno, long week_dayno )
UTC conversion
long long long long long long long long long long long date.to.utc
input.to.utc
inputstr.to.utc
local.to.utc
week.to.utc
( long yearno, long monthno, long month_dayno, long hours, long minutes, long seconds )
( const string value(), const string format() )
( const string date.inputstr(), string date.format(7), const string time.inputstr(), string time.format(7) )
( long local_days, long local_time, ref long utc )
( ) utc.num
utc.to.date
utc.to.input
utc.to.inputstr$ ( long utc, string date.format(7), string time.format(7), ref string local.date(), ref string local.time() ) utc.to.local
( long utc, ref long local_days, ref long local_time ) utc.to.week
( long utc, ref long yearno, ref long monthno, ref long month_dayno, ref long hours, ref long minutes, ref long seconds )
( long lvalue, const string format())
( long utc, ref long week_dayno, ref long year_dayno, ref long weekno, ref long hours, ref long minutes, ref long seconds [, ref long yearno])
( long weekno, long yearno, long week_dayno, long hours, long minutes, long seconds )
Functions reference
12-3
Dates, times, time zones
Time zones
long long long long long choose.time.
zone.from.list
date.to.date
get.time.zone
set.time.zone
timezone.exists
( )
( long in_date, long in_time, const string in_zone(), const string out_zone(), ref long out_date, ref long out_time )
( ref string time_zone() )
( string time_zone(50) )
( string timezone(50) )
Syntax
long choose.time.zone.from.list()
Description
This starts a session where the user can choose a time zone from a list. The function then calls set.timezone() with the time zone selected by the user.
Return values
0
-1 new time zone set user aborted operation; time zone not set
Context
3GL library function.
Syntax
long date.num()
Description
This returns the number of days from 01-01-0001 to the system date.
Functions reference
12-4
Dates, times, time zones
Return values
The number of days from 01-01-0001 to the system date. Or -1 if an error occurs.
Context
Bshell function.
Syntax
long date.to.date( long in_date, long in_time, const string in_zone(), const string out_zone(), ref long out_date, ref long out_time )
Description
This converts a date and time in one time zone to the corresponding date and time in a different time zone.
Arguments
in_date in_time
The date in the source time zone, specified as the number of days since 01-01-0001.
The time in the source time zone, specified as the number of seconds since 00:00 hour.
The source time zone.
in_zone out_zone
The time zone to which the source date and time must be converted.
out_date
The number of days since 01-01-0001 in the target time zone.
out_time
The number of seconds since 00:00 hour in the target time zone.
Return values
0 success
-1 error
Context
3GL library function.
Functions reference
12-5
Dates, times, time zones
Syntax
string date.to.inputstr$( long dayno, string format(7), long length )
Description
This converts a specified number of days since 01-01-0001 to a date input string.
Arguments
dayno
A number of days since 01-01-0001.
format
The format for the date string, specified by using the substitution symbols
%Dxxx[, lang]
or
%D(format)
. See sprintf$().
length
The length of the date string:
6: year represented by 2 characters (century not included)
8: year represented by 4 characters (century included).
Return values
The formatted input string. Or an empty string if an error occurs.
Context
Bshell function.
Example
This example creates a default input string for the data.input function.
string inpstring(8) inpstring = date.to.inputstr$( 727000, "%D002,3", 8 )
If the %D002 format for language 3 is MDY, the string returned is "06171991"
(that is, June 17, 1991). If it is DWY, and the first day of the week is Sunday, the string returned is "2251991" (that is, day 2, week 25, 1991).
Functions reference
12-6
Dates, times, time zones
Syntax
long date.to.num( long yearno, long monthno, long month_dayno )
Description
This returns the number of days since 01-01-0001 for a specified year, month, and day of the month.
Return values
The number of days since 01-01-0001. Or -1 if an error occurs.
Context
Bshell function.
Example
long no_of_days
no_of_days = date.to.num( 1991, 04, 20 ) | Returns 726942
Syntax
long date.to.utc( long yearno, long monthno, long month_dayno, long hours, long minutes, long seconds)
Description
This converts the specified local date and time to UTC long format.
Return values
The UTC long format value. Or -1 if an error occurs.
Context
3GL library function.
Functions reference
12-7
Dates, times, time zones
Example
long utc utc = date.to.utc( 1991, 04, 20, 23, 12, 45 )
Syntax
string dte$()
Desription
This returns the current date and time in the format MMDDYYHHMMSS.
Notes
The standard variable date$ provides the current date in the format DDMMYY.
The standard variable time provides the current time in the format HHMM.
string, as shown in the example below.
Return values
A string containing the current date and time.
Context
Bshell function.
Example
This example prints the current time in the format HH:MM:SS.
string dat(12) dat = dte$() print dat(7;2), ":", dat(9;2), ":", dat(11;2)
Functions reference
12-8
Dates, times, time zones
Syntax
long get.time.zone( ref string time_zone() )
Description
This returns the current time zone. The program must supply a buffer of size 50 to store the result.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long inputstr.to.date( string inputstr(.), string format(7))
Description
This converts a date input string to the number of days since 01-01-0001.
Arguments
inputstr
The date input string, possibly input by the user and retrieved using the function data.input().
format
Indicates the format of the input string, specified by using the substitution symbols
%Dxxx[, lang]
or
%D(format)
. See
Return value
The number of days from 01-01-0001 to the date specified in the input string. Or
-1 if an error occurs.
Functions reference
12-9
Dates, times, time zones
Context
Bshell function.
Example
This example assumes that %D002,3 represents the format MDY.
long dat dat = inputstr.to.date( "06171991", "%D002,3" )
| dat now contains 727000
Syntax
long inputstr.to.utc( const string date.inputstr(), string date.format(7), const string time.inputstr(), string time.format(7) )
Description
This converts the specified local date and time input strings to UTC long format.
Arguments
date.inputstr
A date string (in local time).
date.format
Indicates the format of the date string, by using the substitution symbols
%Dxxx[, lang]
or
%D(format)
. See sprintf$().
time.inputstr
A time string (in local time).
time.format
Indicates the format of the time string, by using the substitution symbols
%Uxxx[, lang]
or
%U(format)
. See sprintf$().
Return values
The UTC long format value. Or -1 if an error occurs.
Context
3GL library function.
Functions reference
12-10
Dates, times, time zones
Syntax
long input.to.utc( const string value(), const string format() )
Description
This converts a local date or local time string to UTC long format.
Arguments
value
A date string or a time string (in local time).
format
Indicates the format of the input string.
For a date string, use the substitution symbols
%Dxxx[, lang]
or
%D(format)
. See sprintf$().
For a time string, use the substitution symbols
%Uxxx[, lang]
or
%U(format)
. See sprintf$().
Return value
The UTC long format value. Or -1 if an error occurs.
Context
3GL library function.
Syntax
long local.to.utc( long local_days, long local_time, ref long utc )
Description
This converts a local date and time to UTC long format.
Functions reference
12-11
Dates, times, time zones
Arguments
local_days
A number of days since 01-01-0001.
local_time
A number of seconds since 00:00 hours.
utc
The UTC long format value corresponding to the specified local date and time.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long num.to.date( long dayno, ref long yearno, ref long monthno, ref long month_dayno )
Description
This converts a specified number of days since 01-01-0001 to the corresponding year, month, and day of the month.
Return values
0
-1 success error
Context
Bshell function.
Functions reference
12-12
Dates, times, time zones
Syntax
string num.to.date$( long dayno, long mode )
Description
This converts a specified number of days since 01-01-0001 to the corresponding date, formatted as a date string. The sequence of day, month, and year in the string depends on the user data settings defined in the data dictionary. The separator character used is also defined in the data dictionary.
Arguments
dayno
A number of days since 01-01-0001.
mode
Specifies certain characteristics of the date string format:
0: Year as YY without separators (for example, 311290)
1: Year as YY with separators (for example, 31/12/90)
2: Year as YYYY without separators (for example, 31121990)
3: Year as YYYY with separators (for example, 31/12/1990).
Return values
The formatted date string. Or an empty string if an error occurs.
Context
Bshell function.
Syntax
long num.to.week( long dayno, ref long week_dayno, ref long year_dayno, ref long weekno [, ref long yearno] )
Description
This converts a specified number of days since 01-01-0001 to the corresponding day of the week, day of the year, and week number of the year.
Functions reference
12-13
Dates, times, time zones
Arguments
dayno
A number of days since 01-01-0001.
week_dayno
The day of the week. This depends on which day is defined as the first day of the week in the user data settings in the data dictionary.
year_dayno weekno yearno
The day number in the year.
The week number in the year. See “Week handling” earlier in this chapter.
The year number. This argument is optional.
Notes
If the day of the week lies in the week that includes the turn of the year, weekno returns either 53, 0, or 1. The rules applied are: n
Yearno argument included
−
If less that 4 days of the week belong to the old year, weekno returns 1 and yearno returns the number of the new year.
−
If 4 or more days belong to the old year, weekno returns 53 and yearno returns the number of the old year.
n
Yearno argument not included
−
If the day belongs to the old year, weekno returns 53.
−
If the day belongs to the new year and there are less that 4 days of the new year in the week, weekno returns 0.
−
If the day belongs to the new year and there are more that 3 days of the new year in the week, weekno returns 1.
Return values
0
-1 success error
Context
Bshell function.
Functions reference
12-14
Dates, times, time zones
Syntax
long set.time.zone( string time_zone(50) )
Description
This sets the local time zone at run time.
Return values
0 success
Context
Bshell function.
Syntax
long time.num()
Description
This returns the current time as the number of seconds since 00:00.
Return values
The current time as the number of seconds since 00:00.
Context
Bshell function.
Functions reference
12-15
Dates, times, time zones
Syntax
long timezone.exists( string timezone(50) )
Description
This checks that the input argument contains the name of a valid time zone.
Return value
0 success
Context
3GL library function.
Syntax
long utc.num()
Description
This returns the current local date and time in UTC long format.
Return values
The UTC long format value. Or -1 if an error occurs.
Context
Bshell function.
Functions reference
12-16
Dates, times, time zones
Syntax
long utc.to.date( long utc, ref long yearno, ref long monthno, ref long month_dayno, ref long hours, ref long minutes, ref long seconds )
Description
This converts a UTC long format value to the corresponding year, month, day, and so on, in local time.
Return values
0 success
Context
3GL library function.
Syntax
string utc.to.input( long lvalue, const string format() )
Description
This converts a UTC long format value to an input date string or an input time string (in local time). The format specified determines whether the function returns a date string or a time string.
Arguments
lvalue
A UTC long format value.
format
The format for the input string.
For a UTC date, use the substitution symbols
%uxxx[,lang]
or
%u(format)
. For a UTC time, use the substitution symbols
%Uxxx[,lang]
or
%U(format)
.
Functions reference
12-17
Dates, times, time zones
Return values
0 success
Context
3GL library function.
Syntax
long utc.to.inputstr$( long utc, string date.format(7), string time.format(7), ref string local.date(), ref string local.time() )
Description
This converts a UTC long format value to a local date string and a local time string.
Arguments
utc
A UTC long format value.
date.format
Indicates the format for the returned date string, by using the substitution symbols
%uxxx[,lang]
or
%u(format)
. See
time.format
Indicates the format for the returned time string, by using the substitution symbols
%Uxxx[,lang]
or
%U(format)
. See
local.date
local.time
The returned local date string.
The returned local time string.
Return values
0
-1 success error
Context
3GL library function.
Functions reference
12-18
Dates, times, time zones
Syntax
long utc.to.local(long utc, ref long local_days, ref long local_time )
Description
This converts a UTC long format value to local date and time.
Arguments
utc
The UTC long format value.
local_days
The local date as the number of days since 01-01-0001.
local_time
The local time as the number of seconds since 00:00 hour.
Return values
0 success
Context
Bshell function.
Syntax
long utc.to.week( long utc, ref long week_dayno, ref long year_dayno, ref long weekno, ref long hours, ref long minutes, ref long seconds [, ref long yearno] )
Description
This converts a UTC long format value to the corresponding day of the week, day of the year, week of the year, and so on, in local time.
Functions reference
12-19
Dates, times, time zones
Arguments
dayno week_dayno year_dayno weekno
The UTC long format value.
The day of the week. This depends on which day is defined as the first day of the week in the user data settings in the data dictionary.
The day number in the year.
The week number in the year. See “Week handling” earlier in this chapter.
The time of day.
hours, minutes, seconds yearno
The year number. This argument is optional.
Notes
If the day of the week lies in the week that includes the turn of the year, weekno returns either 53, 0, or 1. The rules applied are: n
Yearno argument included
−
If less that 4 days of the week belong to the old year, weekno returns 1 and yearno returns the number of the new year.
−
If 4 or more days belong to the old year, weekno returns 53 and yearno returns the number of the old year.
n
Yearno argument not included
−
If the day belongs to the old year, weekno returns 53.
−
If the day belongs to the new year and there are less that 4 days of the new year in the week, weekno returns 0.
−
If the day belongs to the new year and there are more that 3 days of the new year in the week, weekno returns 1.
Return values
0 success
Context
3GL library function.
Functions reference
12-20
Dates, times, time zones
Syntax
long week.to.num( long weekno, long yearno, long week_dayno)
Description
This returns the number of days since 01-01-0001 for a specified week number, year number, and day of the week. The day of the week is interpreted by using the day defined as the first day of the week in the user data settings in the data dictionary (see “Week handling” earlier in this chapter).
Return values
The number of days since 01-01-0001. Or -1 if an error occurs.
Context
Bshell function.
Syntax
long week.to.utc( long weekno, long yearno, long week_dayno, long hours, long minutes, long seconds )
Description
This converts a specified week number, year number, day number in week, and so on, in local time, to UTC long format. For information on week numbering, see “Week handling” earlier in this chapter.
Return values
The UTC long format value. Or -1 if an error occurs.
Context
3GL library function.
Functions reference
12-21
Dates, times, time zones
Functions reference
12-22
Use these functions to perform various directory and file operations – for example: n n n n n n
To open, read, and close directories and directory entries
To move, copy, and delete files
To retrieve file information
To create directories and temporary files
To change the access permissions for a file
To handle sequential file input and output.
string creat.tmp.file$ ( [string pathname] ) long dir.close
string dir.entry
( long dfd )
( long dfd, long read_type, const long return_type, const long filesize, const long mode ) long long dir.open
dir.open.tree
( const string path )
( const string path [, long nlevels] )
( long dfd ) long long long dir.rewind
file.chmod
file.chown
long long long long long file.cp
file.mv
file.mv.across.
hosts file.rm
file.stat
( const string file, long mode )
( string file, string user, string group )
( const string source, const string target )
( const string source, const string target )
( const string source, const string target )
( const string path )
( string file_name(256), ref long file_size [, ref long ctime, ref long mtime, ref long atime ] )
Functions reference
13-1
Directory and file operations
long fstat.info
string getcwd long mkdir long pathname long long long long long long rmdir seq.clearerr
seq.close
seq.eof
seq.error
seq.flush
string seq.getc$ long seq.gets
long long long seq.islocked
seq.lock
seq.open
string seq.putc$ long seq.puts
long seq.read
long long seq.rewind
seq.seek
long seq.tell
string seq.ungetc$ long long seq.unlink
seq.unlock
long seq.write
( long fp, ref long size, ref long mode, ref long inode, ref long dev, ref long uid, ref long gid, ref long nlink, ref long ctime, ref long mtime, ref long atime )
( )
( string path_name$ )
( string file_basename(16), string file_type, ref string file_path(256) )
( const string path )
( long fp )
( long fp )
( long fp )
( long fp )
( long fp )
( long fp )
( ref string line(), long nrbytes, long fp )
( long mode, long offset, long size, long fp )
( long mode, long offset, long size, long fp )
( string file(128), string openmode(2) [, ref string pathnm()] )
( string char, long fp )
( string line(2048), long fp )
( ref string buffer(), long nrbytes, long fp )
( long fp )
( long offset, long opt, long fp )
( long fp )
( string char, long fp )
( string path_name(128) )
( long mode, long offset, long size, long fp )
( string buffer(2048), long nrbytes, long fp )
Functions reference
13-2
Directory and file operations
long stat.info
( string file_name(256), ref long size, ref long mode, ref long inode, ref long dev, ref uid, ref long gid, ref long nlink, ref long ctime, ref long mtime, ref long atime )
Syntax
string creat.tmp.file$( [string pathname] )
Description
This creates a temporary file. By default, the file is created in the current directory. To create the file in a different directory, use the optional pathname argument to specify the full path to the required directory.
In UNIX environments, a unique temporary file is created with UNIX-privilege mode 0664.
Notes
It is recommended that you use this function in conjunction with the BSE_TMP environment variable. You can use the function bse.tmp.dir$() to retrieve the name of the directory defined by this variable. For example: creat.tmp.file$( bse.tmp.dir$())
Return values
The name of the temporary file.
Context
Bshell function.
Functions reference
13-3
Directory and file operations
Syntax
long dir.close( long dfd )
Description
This closes a specified directory and frees all memory allocated to it. The dfd argument is the pointer to the directory returned by dir.open() or dir.open.tree() when the directory was opened.
Return values
>=0 success
-1 no free pointer
-2 directory could not be opened or found
-3 bad directory descriptor
Context
Bshell function.
Syntax
string dir.entry( long dfd, long read_type, const long return_type, const long filesize, const long mode )
Description
This retrieves entries from a previously opened directory. It retrieves the entries sequentially.
Arguments
dfd read_type
The pointer to the required directory, as returned when the directory was opened by dir.open() or dir.open.tree().
Specifies the type of entry to be retrieved. Possible values are:
TDIR
TFILE directories files
TDIR+TFILE directories and files
Functions reference
13-4
Directory and file operations
return_type
Returns the type of entry retrieved. Possible values are:
TDIR
TFILE directory file
filesize mode
Returns the size of the entry retrieved.
If the user can access the entry, this argument returns the type of access the user has. Possible options (returned as a bitset) are:
STAT_READABLE
STAT_WRITEABLE
STAT_EXECUTABLE read read, write, and delete run program
Return values
The directory entry. Or an empty string if the end of the entry list has been reached.
Context
Bshell function.
Syntax
long dir.open( const string path )
Description
This reads the specified directory into memory. The path argument can have a maximum length of 2048 characters.
The function returns a pointer (dfd) to the directory data. dir.entry() ,
Return values
>0
-1
-2
-3 a pointer to the directory data no free pointer directory could not be opened or found bad directory descriptor
Functions reference
13-5
Directory and file operations
Context
Bshell function.
Syntax
long dir.open.tree( const string path [, long nlevels] )
Description
This is similar to dir.open() in that it reads a specified directory into memory.
However, dir.open.tree() can retrieve up to 256 directory levels.
The function returns a pointer (dfd) to the directory data. dir.entry() ,
Arguments
path
The path to the required directory. This can have a maximum length of 2048 characters.
nlevels
Use this optional argument to indicate the number of directory levels that must be read. The default is one.
Notes
When a large directory tree is requested, this function can consume a large amount of memory and CPU time. This may block other processes in the same bshell for several minutes or longer, depending on the overall system load.
Return values
>0 a pointer to the directory data
-1 no free pointer
-2
-3 directory could not be opened or found bad directory descriptor
Context
Bshell function.
Functions reference
13-6
Directory and file operations
Syntax
long dir.rewind( long dfd )
Description
This resets the read pointer of the specified directory to the beginning of the directory entry list. The dfd argument is the pointer to the directory returned by
Return values
>=0 success
-1 no free pointer
-2 directory could not be opened or found
-3 bad directory descriptor
Context
Bshell function.
Syntax
long file.chmod( const string file, long mode )
Description
This sets the access permissions for a specified file.
Functions reference
13-7
Directory and file operations
Arguments
file
The name of the file.
mode
The type of access permissions that must be set. This can be a combination of the following values:
User/owner
S_IRWXU
S_IRUSR
S_IWUSR
S_IXUSR
Group read, write, execute read write execute, search
S_IRWXG
S_IRGRP
S_IWGRP
S_IXGRP
Other (UNIX only) read, write, execute read write execute, search
S_IRWXO
S_IROTH
S_IWOTH
S_IXOTH read, write, execute read write execute, search
Note
Setting file access permissions is a system-dependent feature. To enable applications to be system independent, this function does not return an error code when a particular feature is unavailable.
Return values
1
<0 success error
Context
Bshell function.
Functions reference
13-8
Directory and file operations
Syntax
long file.chown( string file, string user, string group )
Description
This changes the owner and/or group of a file. You can use a single call to change both the owner and the group. Alternatively, you can specify either the
user argument or the group argument as an empty string.
Arguments
file user
The name of the file.
The new owner of the file.
group
The new group of the file.
Note
Setting users and groups for files is a system-dependent feature. To enable applications to be system independent, this function does not return an error code when a particular feature is unavailable.
Return values
1
<0 success error
Context
Bshell function.
Syntax
long file.cp( const string source, const string target )
Description
This copies a specified source file to a specified target file. Both files can be either local or remote. They can also be on different hosts (provided that the bshell can access both hosts).
Functions reference
13-9
Directory and file operations
Return values
1
<0 success error
Context
3GL library function.
Syntax
long file.mv( const string source, const string target )
Description
This moves a specified source file to the location specified in the target argument. The file can be either local or remote. Both source and target must be on the same host.
Return values
1
<0 success error
Context
Bshell function.
Syntax
long file.mv.across.hosts( const string source, const string target )
Description
This moves a specified source file to the location specified in the target argument. The file can be either local or remote. Source and target can be on different hosts.
Functions reference
13-10
Directory and file operations
Return values
1
<0 success error
Context
3GL library function.
Syntax
long file.rm( const string path )
Description
This deletes a specified local or remote file. The path argument must include the full path to the file, including the host name, where appropriate. For example:
"host!/usr/myfile"
.
Return values
1
<0 success error
Context
Bshell function.
Syntax
long file.stat( string file_name(256), ref long file_size
[, ref long ctime, ref long mtime, ref long atime ] )
Description
This returns information about a specified file. It is a short version of the
Functions reference
13-11
Directory and file operations
Arguments
file_name
The name of the file for which information is required.
file_size
The file size in bytes.
ctime mtime atime
The time when the file status was last changed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
The time when the file was last modified, as a number of seconds since 00:00:00 GMT, January 1, 1970.
The time when the file data was last accessed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
Return values
0 file exists
<>0 operating system error code
Context
Bshell function.
Syntax
long fstat.info( long fp, ref long size, ref long mode, ref long inode, ref long dev, ref long uid, ref long gid, ref long nlink, ref long ctime, ref long mtime, ref long atime )
Description
This returns information about a specified file. It provides the same information as stat.info(). But instead of retrieving information about a named file, it returns information about an open file that is known by the file descriptor fp. This descriptor can be obtained, for example, from a successful seq.open() call.
Functions reference
13-12
Directory and file operations
Arguments
fp size
The file descriptor, as returned, for example, by seq.open().
The file size in bytes.
mode
This contains a bit pattern that indicates the access permission (posix) of the file. Use the following defines to check the file mode:
S_IRWXU read, write, execute permission by owner
S_IRUSR read permission by owner
S_IWUSR write permission by owner
S_IXUSR execute, search permission by owner
S_IRWXG read, write, execute permission by group
S_IRGRP read permission by group
S_IWGRP write permission by group
S_IXGRP execute, search permission by group
S_IRWXO read, write, execute permission by others
S_IROTH read permission by others
S_IWOTH write permission by others
S_IXOTH execute, search permission by others
S_ISUID
S_ISGID set user id on execution (sbit) set group id on execution (sbit)
S_ISVTX save text after execution inode number.
Device where file is stored.
inode dev uid gid nlink ctime
User ID of the file’s owner.
The file’s group ID.
Number of links to the file.
The time when the file status was last changed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
mtime
The time when the file was last modified, as a number of seconds since 00:00:00 GMT, January 1, 1970.
atime
The time when the file data was last accessed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
Functions reference
13-13
Directory and file operations
Notes
You can use the following macros to check the file type: if ( S_ISDIR(mode) ) if ( S_ISREG(mode) ) if ( S_ISBLK(mode) ) if ( S_ISCHR(mode) )
| file is a directory (perm: drwxrwxrwx)
| file is an ordinary file (perm: -
| rwxrwxrwx)
| file is a block-oriented device (disk or
| tape) (perm: brwxrwxrwx)
| file is a character-oriented device perm:
| crwxrwxrwx) if ( S_ISFIFO(mode) ) | file is a fifo special file
| (perm: prwxrwxrwx) if ( S_ISSOCK(mode) ) | file is a socket file (perm: srwxrwxrwx)
Return values
0 success
<>0 operating system error code
Context
Bshell function.
Syntax
string getcwd( )
Description
This returns the current path as a string. Note that on Windows NT systems, pathnames can include drive letters (for example, c:/baan/bin).
Return values
The current path as a string. Or an empty string if an error occurs.
Context
Bshell function.
Functions reference
13-14
Directory and file operations
Syntax
long mkdir( string path_name$ )
Description
This creates a specified directory (local or remote). You must have write permission in the parent directory to do this. Access permissions for the new directory are set to read, write, and execute for all users. The path_name$ argument must include the full path to the directory, including the host name, where appropriate. For example: mkdir( "host1!/usr/mydir" )
Return values
1
0
-1 success path already exists (only returned when creating a local directory) failure; probably no permission
Context
Bshell function.
Syntax
long pathname( string file_basename(16), string file_type, ref string file_path(256) )
Description
This searches for and returns the location of a specified file.
The function uses the file $BSE/lib/fdver.pack_combination to find the file. ver refers to a particular release of the software; pack_combination refers to a particular package combination.
It is not necessary to use this function within functions such as db.bind(). These also use the file $BSE/lib/fdver.pack_combination to search for a path name.
Functions reference
13-15
Directory and file operations
Arguments
file_basename
The name of the file that must be found.
The file name must begin with xppmmm where pp is a package code, mmm is a module code, and x is a single character that corresponds to the file type, as shown in column one of the following list:
Character Description file_type argument
i m p o f d r data/domain definition report object form menu program script include file
D
O
O
S
M
P
P
For example, when searching for a report, the file name specified must begin with ’r’. The name of the report object located begins with ’o’.
file_type
The file type. Use the values shown in column three of the above list.
file_path
This returns the full path to the specified file.
If the file is not found, it returns the full path (including filename) where the file should be created.
If the file_type is unknown, or file_basename starts with an invalid character, this argument returns the value of
file_basename.
Notes
Language codes are relevant to reports, forms, and menus. You can specify the language code for a report, form, or menu file by appending it to the file name
(that is, adding it as the 16 th
character). If you do not include this, the current language is assumed.
Return values
0 success
ENOENT file not found
Functions reference
13-16
Directory and file operations
Context
Bshell function.
Example:
string file_path(256) if pathname( "rpctst121200010", "O", file_path ) then message( "File not found, must be created in %s", file_path ) endif
Syntax
long rmdir( const string path )
Description
This deletes the specified directory (local or remote). The path argument must include the full path to the directory, including the host name, where appropriate.
For example: "host!c:\usr".
Return values
1
<0 success error
Context
Bshell function.
Syntax
long seq.clearerr( long fp )
Description
This resets the error and end-of-file indicators for the specified file. fp is the file pointer returned by seq.open() when the file was opened.
Functions reference
13-17
Directory and file operations
Return values
0
-1 success error; probably fp not connected
Context
Bshell function.
Syntax
long seq.close( long fp )
Description
This flushes the buffers associated with the specified file and closes the file. fp is the file pointer returned by seq.open() when the file was opened. Buffers allocated by the standard i/o system are also flushed and closed. These actions are performed automatically when the process exits.
Return values
0
–1 success error; probably fp not connected (the last system error is available in the
28) – for a list of error codes, see Chapter 10, Errors, in
U7168A US
BaanERP Tools: Programming Features
Context
Bshell function.
Syntax
long seq.eof( long fp )
Description
This checks the end-of-file indicator of a specified file. fp is the file pointer returned by seq.open() when the file was opened.
Functions reference
13-18
Directory and file operations
An end-of-file indication lasts until it is cleared by seq.clearerr() or until the file is closed.
Return values
0
>0
-1 end-of-file indicator not set end-of-file indicator set error; probably fp not connected
Context
Bshell function.
Syntax
long seq.error( long fp )
Description
This checks the error indicator of a specified file. The error indicator is set when an error occurs while reading from or writing to the file. It lasts until it is cleared by seq.clearerr() or until the file is closed. fp is the file pointer returned by
Return values
0
>0
-1 error indicator not set error indicator set error; probably fp not connected
Context
Bshell function.
Functions reference
13-19
Directory and file operations
Syntax
long seq.flush( fp )
Description
This causes all buffered data for a specified file to be written to that file. The file remains open. fp is the file pointer returned by seq.open() when the file was opened.
Return values
0
-1 success error; probably fp not connected (the last system error is available in the
28) – for a list of error codes, see Chapter 10, Errors, in U7168A US
BaanERP Tools: Programming Features)
Context
Bshell function.
Syntax
string seq.getc$( long fp )
Description
This returns the next character from a specified file. fp is the file pointer returned by seq.open() when the file was opened. An empty string indicates either that the end-of-file has been reached or that an error has occurred.
Context
Bshell function.
Functions reference
13-20
Directory and file operations
Syntax
long seq.gets( ref string line(), long nrbytes, long fp [, mode, ref long there.was.more] )
Description
This reads one or more characters from a specified file.
Arguments
line nrbytes fp mode
This stores the retrieved characters.
The maximum number of bytes to be read. Note that the function stops retrieving characters when a new line character is read or when the end of file is reached. The maximum number of characters that can be read is 2048.
The pointer to the file from which the characters are to be read, as returned by seq.open() when the file was opened.
Use this optional argument to specify the read mode for
GETS_NORMAL
The function continues reading characters until either the buffer
(line) is full, a new line character is read, or EOF is reached. If the buffer is full, any remaining characters on the line being read are discarded. This is the default mode.
GETS_ALL_CHARS
The function continues reading characters until either the buffer
(line) is full, a new line character is read, or EOF is reached. If the buffer is full, the next seq.gets() call starts reading at the point where the current seq.gets() finished. The use of this mode ensures that all characters available in input file are eventually returned.
GETS_SKIP_ALL
This is the same as GETS_NORMAL, except that if the last line in the file does not end with a new line character, that line is discarded completely and EOF is returned.
Functions reference
13-21
Directory and file operations
there.
was.more
When characters are discarded in GETS_NORMAL or
GETS_SKIP_ALL mode, or when more characters are available in the line (but the buffer is full) in GETS_ALL_CHARS mode, this argument is set to 1. Otherwise, the argument returns 0.
Return values
0
-1 success error; probably fp not connected or end of file reached
Context
Bshell function.
Syntax
long seq.islocked( long mode, long offset, long size, long fp )
Description
This checks whether a specified file or segment of a file has been locked by
Arguments
mode
The type of lock you want to check for:
SEQ_R_LCK
SEQ_W_LCK read lock write lock
SEQ_F_R_LCK file lock (read)
SEQ_F_W_LCK file lock (write)
offset, size
To check whether a particular segment of the file has been locked, use these arguments to specify the offset of the segment from the beginning of the file and the length of the segment.
fp
The file pointer returned by seq.open() when the file was opened.
Functions reference
13-22
Directory and file operations
Return values
0 file or file segment not locked
<>0 file or file segment locked
Context
Bshell function.
Syntax
long seq.lock( long mode, long offset, long size, long fp )
Description
This sets read and write locks on a specified file or segment of a file.
Arguments
mode offset, size fp
The type of lock to set:
SEQ_R_LCK
SEQ_W_LCK read lock write lock
SEQ_F_R_LCK file lock (read)
SEQ_F_W_LCK file lock (write)
To set a lock on a segment of the file, use these arguments to specify the offset of the segment from the beginning of the file and the length of the segment.
To extend a lock to the end of the file, set size to 0. To set a lock on the entire file, set both arguments to 0.
The file pointer returned by seq.open() when the file was opened.
Functions reference
13-23
Directory and file operations
Notes
A read lock prevents any process from setting a write lock on the protected file or file segment. Multiple read locks can be set for the same file or file segment.
The file with which the lock is associated must have been opened with read access (see seq.open() ).
A write lock prevents any process from setting a read lock or a write lock on the protected file or file segment. Only one write lock can exist for a particular file or file segment. The file with which the lock is associated must have been opened with write access.
Return values
>= 0 success
-1 error; probably fp not connected
< -1 operating system error code
Context
Bshell function.
Syntax
long seq.open( string file(128), string openmode(2) [, ref string pathnm()] )
Description
This opens a specified file. It uses the file $BSE/lib/fdver.pack_combination to find the file. ver refers to a particular release of the software; pack_combination refers to a particular package combination (see pathname()).
Arguments
file
The file name.
Functions reference
13-24
Directory and file operations
openmode pathnm
The mode in which the file must be opened. This can be one of the following options:
"r" Open for reading. The current file position is placed at the start of the file.
"w"
"a"
Open for writing. The file is created if it does not already exist. The current file position is placed at the start of the file.
Open for writing. The file is created if it does not already exist. The current file position is placed at the end of the file.
"x"
"r+"
Open for writing. This is the same as "w", except that the function fails if the file already exists.
Same as "r", but the file can also be written to.
"w+" Same as "w", but the file can also be read.
"a+" Same as "a", but the file can also be read.
"x+" Same as "x", but the file can also be read.
Use the following modes to indicate whether the file is a binary or a text file. You can combine one of these modes with any one of the previous modes (for example, "rt+").
"b" Use for binary files. This is the default mode and need not be specified.
"t" The line separator(s) for text-files are different on
Windows NT and UNIX systems. CRLF on the former;
LF only on the latter. In addition, a Windows NT text file can include an EOF-character (^Z) that indicates the end of the file. This character should not be returned to a program reading the file.
So, you must specify the "t" option when reading from or writing to a text file on Windows NT systems (for example, "at+".) This ensures that line separators and
EOF characters are handled correctly. Never use the "t" option when opening a binary file; on Windows NT systems this will corrupt the file data. The "t" option has no effect on UNIX systems.
This returns the full path to the file.
Functions reference
13-25
Directory and file operations
Notes
When you open a file for reading and writing, you cannot follow an output operation directly by an input operation. You must call seq.seek() or
Also, you cannot follow an input operation directly by an output operation, unless the input operation encounters the end-of-file indicator. You must call
operation.
Return values
>= 1 success; file pointer returned for use in subsequent operations
< 1 error; that is, the negative value of the system error (for example, for a permission error, the system returns 13 and the function returns -13, or if the internal table is full, the function returns -EAGAIN).
Context
Bshell function.
Syntax
string seq.putc$( string char, long fp )
Description
This writes a specified character to a specified file. fp is the file pointer returned by seq.open() when the particular file was opened.
Return values
The character written to the file. Or an empty string if the end-of-file was reached or an error occurred.
The last system error is available in the e variable – for example, for file system full, e will be ENOSPC (that is, 28) – for a list of error codes, see Chapter 10,
Errors, in U7168A US BaanERP Tools: Programming Features.
Context
Bshell function.
Functions reference
13-26
Directory and file operations
Syntax
long seq.puts( string line(2048), long fp )
Description
This writes the specified characters to a specified file, and appends a new line character. fp is the file pointer returned by seq.open() when the particular file was opened.
Return values
0
-1 success error; probably fp not connected (the last system error is available in the e variable – for example, for file system full, e will be ENOSPC
(that is, 28) – for a list of error codes, see Chapter 10, Errors, in U7168A
US BaanERP Tools: Programming Features)
Context
Bshell function.
Syntax
long seq.read( ref string buffer(), long nrbytes, long fp )
Description
This reads a specified number of bytes from a specified file into buffer. fp is the file pointer returned by seq.open() when the particular file was opened.
Return values
>0
0
-1 number of bytes read end-of-file error; probably fp not connected
Context
Bshell function.
Functions reference
13-27
Directory and file operations
Syntax
long seq.rewind( long fp )
Description
This sets the current file position to the beginning of the file. It is equivalent to: seq.seek(0, 0, fp)
.
Return values
0
-1 success error; probably fp not connected
Context
Bshell function.
Syntax
long seq.seek( long offset, long opt, long fp )
Description
This changes the current file position.
Arguments
offset
The new file position, as a number of bytes.
opt
0
1
2
This determines whether the specified offset is from the beginning of the file, the end of the file, or the current file position: new position is offset from the beginning of the file new position is offset from the current file position new position is offset from the end of the file
fp
The file pointer returned by seq.open() when the particular file was opened.
Functions reference
13-28
Directory and file operations
Return values
>=0 success; returns new position in bytes from the beginning of the file
<0 error; probably fp not connected; current file position is not changed
Context
Bshell function.
Syntax
long seq.tell( long fp )
Description
This returns the current file position, relative to the beginning of the file. The file position is measured in bytes. fp is the file pointer returned by seq.open() when the particular file was opened.
Take care when using this function on files that have been opened in append mode (that is, with the openmode argument set to a or a+). Before calling
Return values
>=0 success
-1 error; probably fp not connected
Context
Bshell function.
Syntax
string seq.ungetc$( string char, long fp )
Description
This puts back a specified character, retrieved by seq.getc$(). The character will be returned by the next seq.getc$() call on that file. This function works only if
Functions reference
13-29
Directory and file operations
something has been read from the file and if the file is buffered. fp is the file pointer returned by seq.open() when the particular file was opened.
Return values
The character written to the file. Or an empty string if end-of-file is reached or an error occured.
Context
Bshell function.
Syntax
long seq.unlink( string path_name(128) )
Description
This deletes the file indicated by the path_name argument.
Return values
0
<0 success error; that is, the negative value of the operating system error
Context
Bshell function.
Syntax
long seq.unlock( long mode, long offset, long size, long fp
)
Description
This removes a lock set by seq.lock().
Functions reference
13-30
Directory and file operations
Arguments
mode
The type of lock to remove:
SEQ_R_LCK
SEQ_W_LCK read lock write lock
SEQ_F_R_LCK file lock (read)
SEQ_F_W_LCK file lock (write)
offset, size
To remove a lock from a segment of the file, use these arguments to specify the offset of the segment from the beginning of the file and the length of the segment.
To remove a lock that extends to the end of the file, set size to 0.
To remove a lock from the entire file, set both arguments to 0.
fp
The file pointer returned by seq.open() when the file was opened.
Notes
All locks set on a file by a particular process are removed automatically when the file descriptor for the file is closed by the process (see seq.close()) or when the process itself terminates.
Return values
>=0 success
-1 error; probably fp not connected
<-1 negative error value
Context
Bshell function.
Syntax
long seq.write( string buffer(2048), long nrbytes, long fp)
Description
This appends data from the specified buffer to the specified file, beginning at the current file position. The nrbytes argument indicates the number of bytes to be
Functions reference
13-31
Directory and file operations
written to the file. fp is the file pointer returned by seq.open() when the particular file was opened.
Return value
>0
0
-1 number of bytes actually written end-of-file error; probably fp not connected
(the last system error is available in the e variable – for example, for file system full, e will be ENOSPC (that is, 28) – for a list of error codes, see
Chapter 10, Errors, in U7168A US BaanERP Tools: Programming
Features)
Context
Bshell function.
Syntax
long stat.info( string file_name(256), ref long size, ref long mode, ref long inode, ref long dev, ref long uid, ref long gid, ref long nlink, ref long ctime, ref long mtime, ref long atime )
Description
This returns information about a named file. It provides the same information as
Arguments
file_name
The name of the file. All files listed in the path name must be searchable. To specify a remote file, include the host name. For example: "host!/usr/myfile" .
size
The file size in bytes.
Functions reference
13-32
mode inode dev uid gid nlink ctime mtime atime
Directory and file operations
This contains a bit pattern that indicates the access permission
(posix) of the file. Use the following defines to check the file mode:
S_IRWXU read, write, execute permission by owner
S_IRUSR read permission by owner
S_IWUSR write permission by owner
S_IXUSR execute, search permission by owner
S_IRWXG read, write, execute permission by group
S_IRGRP read permission by group
S_IWGRP write permission by group
S_IXGRP execute/search permission by group
S_IRWXO read, write, execute permission by others
S_IROTH read permission by others
S_IWOTH write permission by others
S_IXOTH execute, search permission by others
S_ISUID
S_ISGID set user id on execution (sbit) set group id on execution (sbit)
S_ISVTX save text after execution inode number.
Device where file is stored.
User ID of the file’s owner.
The file’s group ID.
Number of links to the file.
The time when the file status was last changed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
The time when the file was last modified, as a number of seconds since 00:00:00 GMT, January 1, 1970.
The time when the file data was last accessed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
Functions reference
13-33
Directory and file operations
Notes
You can use the following macros to check the file type: if ( S_ISDIR(mode) ) if ( S_ISREG(mode) ) if ( S_ISBLK(mode) ) if ( S_ISCHR(mode) )
| file is a directory (perm: drwxrwxrwx)
| file is an ordinary file (perm: -rwxrwxrwx)
| file is a block-oriented device
| (disk or tape)(perm: brwxrwxrwx)
| file is a character-oriented device
| (perm: crwxrwxrwx) if ( S_ISFIFO(mode) ) | file is a fifo special file
| (perm: prwxrwxrwx) if ( S_ISSOCK(mode) ) | file is a socket file (perm: srwxrwxrwx)
Return values
0 success
<>0 operating system error code
Context
Bshell function.
Example
long ret long size, mode, inode, dev, uid, gid, nlink, ctime, atime, long mtime string file_name(256) file_name = "/usr/bse/lib/ipc_info" ret = stat.info( file_name, size, mode, inode, dev, uid, gid, nlink, ctime, mtime, atime ) if ret then
| stat.info failed, probably file not found endif if ( S_ISDIR( mode ) ) then sprintf$( "%s is a directory", file_name ) endif if ( bit.and( S_IRUSR, mode ) ) then sprintf$( "User has read permission" ) endif if ( bit.and( S_IWUSR, mode ) ) then sprintf$( "User has write permission" ) endif if ( bit.and( S_IXUSR, mode ) ) then sprintf$( "User has execute permission" ) endif
Functions reference
13-34
Use these functions to execute functions in a dynamic link library (DLL) at runtime. For an overview of dynamic link libraries and runtime dynamic linking, see Chapter 8, Dynamic link libraries, in U7168A US BaanERP Tools:
Programming Features.
long long long long long exec_dll_function ( string dll_name, string function_name [, ref void return_value, arg, ...] ) exec_function ( long dll_id, long func_id [, ref void return_value, arg,
...] ) get_function load_dll parse_and_exec_ function
( long dll_id, string function_name )
( string dll_name [, long overload ] )
( string dll_name, string function_call [, ref void return_value, ref string return_call() ] )
Syntax
long exec_dll_function( string dll_name, string function_name [, ref void return_value, arg, ...] )
Description
This loads a specified DLL and executes a specified function within that DLL. It provides a fast algorithm for executing a DLL function that is to be executed only once. If the DLL is already loaded, the identification number of the loaded
DLL is used to search for the specified function. Otherwise, a
Functions reference
14-1
DLL functions (executing)
load_dll(dll_name, 0)
call is executed automatically. If a function is to be called more than once, it is faster to use the load_dll(), get_function(), and
Arguments
dll_name
The name of the DLL that must be loaded.
function_name
The name of the function that must be executed.
return_value arg ...
This stores the return value (if any) of the function.
The arguments of the function (if any). These are function dependent.
Return values
0
-1
-2 success error; DLL not found error; function not found
Context
Bshell function.
Example
long ret, ret2 ret=exec_dll_function("otisfc0220",
"ptisfc0220.store.quantities", ret2, tibom010.noun, tibom010.qana, tibom010.scpf )
Syntax
long exec_function( long dll_id, long func_id [, ref void return_value, arg, ...] )
Description
This executes a function previously loaded by a call to get_function(). After the function has been loaded, you can call exec_function() any number of times to execute the function.
Functions reference
14-2
DLL functions (executing)
Arguments
dll_id funct_id
The identification number of the DLL that contains the function, as returned by load_dll().
The identification number of the function, as returned by
return_value
This stores the return value (if any) of the function.
arg ...
The arguments of the function (if any). These are function dependent.
Return values
0
-1
-2 success error, DLL not found error, function not found
Context
Bshell function.
Example
This example loads the DLL "tisfc0220" and executes the function
"tisfc0220.store.quantities" contained in that DLL.
long dll_id, func_id long ret, ret2 dll_id = load_dll("otisfc0220") if dll_id then func_id = get_function( dll_id,
"tisfc0220.store.quantities" ) if func_id then select tibom010.noun, tibom010.qana, tibom010.scpf
from tibom010 selectdo ret = exec_function( dll_id, func_id, ret2, tibom010.noun, tibom010.qana, tibom010.scpf ) endif endif endselect
Functions reference
14-3
DLL functions (executing)
Syntax
long get_function( long dll_id, string function_name )
Description
This loads a specified function from a previously loaded DLL. It returns an identification number for the function.
Arguments
dll_id
The identification number of the DLL that contains the function, as returned by load_dll().
funct_name
The function name.
Return values
>0
0 function identifier error; function not found or DLL not loaded
Context
Bshell function.
Syntax
long load_dll( string dll_name [, long overload ] )
Description
This loads a specified DLL.
You can use it in combination with get_function() and exec_function() to call and execute a function in a DLL. These three functions provide a fast algorithm for accessing a function that is to be executed more than once. You load the DLL and function only once and can then execute the function any number of times.
identify a particular DLL.
You can also use load_dll() to replace one or more functions within a DLL by overloading a different DLL containing functions with the same names and
Functions reference
14-4
DLL functions (executing)
arguments. But note that once a function has been loaded from a DLL, that DLL cannot subsequently be overloaded.
For a full discussion on function overloading, see “Function overloading” in
Chapter 8 in U7168A US BaanERP Tools: Programming Features.
Arguments
dll_name
The name of the DLL.
overload
This optional argument sets the overload flag for the specified
DLL. The possible values are:
0 places the DLL as the last element in the search list of all dynamically loaded DLLs – this is the default option
DLL_OVERLOAD places the DLL as the first element in the search list of all dynamically loaded DLLs
DLL_SILENT_ERR suppresses error messages
You can combine DLL_SILENT_ERR with either of the other options.
Notes
You cannot load the same DLL more than once within the same process. If you call load_dll() a second time, it returns the same identification number as it did the first time. However, you can use subsequent calls to load_dll() to change the value of the overload flag.
The load_dll() function must be called before the first function call to the DLL.
Once a function has been found in one of the loaded DLLs, the function address is resolved. That address is used for all subsequent function calls; it cannot be replaced by overloading another DLL.
Return values
>0
0
DLL identifier error; DLL not found
Context
Bshell function
Functions reference
14-5
DLL functions (executing)
Syntax
long parse_and_exec_function( string dll_name, string function_call [, ref void return_value, ref string return_call() ] )
Description
This function is similar to exec_dll_function(). It loads a specified DLL and parses and executes a specified function within that DLL. If the DLL is already loaded, the identification number of the loaded DLL is used to search for the specified function. Otherwise, a load_dll(dll_name, 0)
call is executed automatically.
Use this function only when the function and its arguments are known only at runtime. The function is intended for handing function calls received as strings from other processes.
Arguments
dll_name
The name of the DLL that must be loaded.
function_call
A string containing the function name and arguments. You can specify any function in this argument, except one that contains array arguments. To execute a function with array arguments, use exec_dll_function() instead.
return_value
This stores the return value (if any) of the function.
return_call
If the function call includes reference arguments, the value of these can change during execution of the function. This returns the parsed function call, so that you can check the values of reference arguments.
Note
If the function call contains reference arguments, the result of the function call
(stored in return_call) cannot become longer than the length of the function_call argument.
Return values
0
-1 success error; DLL not found
Functions reference
14-6
DLL functions (executing)
-2
-3 error; function not found syntax error in function call
Context
Bshell function.
Example
| assume the function my_max in DLL ttstdlib which
| returns the maximum of the two given arguments.
| object ottstdlib belongs to DLL ttstdlib long ret, ret2 long a, b string ret_call(80) string funccall(80) a = 30 b = 40 funccall = sprintf$("my_max(%d,%d)", a, b) ret = parse_and_exec_function( "ottstdlib", funccall, ret2, ret_call )
| ret2 becomes 40
| ret_call becomes "my_max(30,40)"
Functions reference
14-7
DLL functions (executing)
Functions reference
14-8
Dynamic SQL enables programs to compose and execute SQL statements at runtime. This is necessary, for example, when SQL statements are composed in response to user input.
You use the functions described in this section to handle dynamic SQL queries.
Use sql.parse() to define the query. Once the query has been defined, use the other functions to bind variables in the SQL statement to BAAN 4GL variables, to execute the query, to fetch the results, and to end and delete the query. Note that there is no need to bind external variables. Once you have defined a query using sql.parse(), you can execute it any number of times, using different variables, without redefining it.
The sequence in which you use the functions is as follows: sql.parse() sql.select.bind() sql.where.bind() sql.exec() sql.fetch() sql.fetch()
...
sql.break() sql.select.bind() sql.where.bind() sql.exec() sql.fetch() sql.fetch()
...
sql.break() sql.close
For a general discussion of database handling, and embedded and dynamic SQL, see Chapter 5, Database handling, in U7168A US BaanERP Tools: Programming
Features.
Functions reference
15-1
Dynamic SQL queries
long long long long long long long long sql.break
sql.close
sql.exec
sql.fetch
sql.parse
( long sql_id )
( long sql_id )
( long sql_id )
( long sql_id )
( string query(.), [ long suppr_err ] ) sql.select.bind
( long sql_id, long pseudo_var, var_name(.) ) sql.set.rds.full
( long sql.id, long size ) sql.where.bind
( long sql_id, long pseudo_var, var_name(.) )
Syntax
long sql.break( long sql_id )
Description
This stops the specified query and clears any interim results. The sql_id argument indicates the query ID, as returned by sql.parse(). The function does not remove the query itself. So the query can be reused after binding to another variable, for example.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
15-2
Dynamic SQL queries
Syntax
long sql.close( long sql_id )
Description
This deletes all internal information relating to the specified query. The sql_id argument indicates the query ID, as returned by sql.parse().
Return values
0 success
<>0 error
Context
Bshell function.
Syntax
long sql.exec( long sql_id )
Description
This initializes the specified query and evaluates any bind variables in the
WHERE clause. Before calling this function, you must previously have called
returned by sql.parse().
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
15-3
Dynamic SQL queries
Syntax
long sql.fetch( long sql_id )
Description
This reads a single query result and stores the values retrieved in the variables specified in the SELECT list. The sql_id argument indicates the query ID, as returned by sql.parse(). You must call the function for each individual record in the result set.
Return values
0 success
<>0 error
The function returns eendfile
when it reaches the end of the result set. It returns enorec
if the set is empty.
Context
Bshell function.
Syntax
long sql.parse( string query(.), [ long suppr_err ] )
Description
This defines an SQL query that you can subsequently execute and retrieve the results of by using the other dynamic SQL functions. The query takes the form of a SELECT statement (see Chapter 5, Database handling, in U7168A US
BaanERP Tools: Programming Features). If you set the optional argument
suppr_err to 1, this suppresses error messages (the predefined variable e contains the error number).
Return values
0
>0 error query ID; this is used by the other functions to identify the particular query
Functions reference
15-4
Dynamic SQL queries
Context
Bshell function.
Example
sql_id_1 = sql.parse( "select tccom010.cuno from tccom010")
Syntax
long sql.select.bind( long sql_id, long pseudo_var, var_name(.) )
Description
When you define an SQL statement with the sql.parse() function, you can define a pseudo variable for any or all of the fields specified in the SELECT statement.
You do this by appending a number, prefixed by a colon [:], to each field. You use sql.select.bind() to bind a pseudo variable to a BAAN 4GL variable. As a result, the values of the field retrieved by the SELECT statement are stored in the
4GL variable. They can then be used elsewhere in the program.
Note that it is not necessary to bind external variables.
Arguments
sql_id var_name
The query ID, as returned by sql.parse().
pseudo_var
The pseudo variable from the SELECT list. This is always a number.
The name of the BAAN 4GL variable to which the pseudo variable must be bound.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
15-5
Dynamic SQL queries
Example
long sql_id domain tccom.bpid, customer sql_id = sql.parse( "select tccom100.cuno:1 " &
"from tccom100" ) sql.select.bind( sql_id, 1, customer )
.....
print customer
Syntax
long sql.set.rds.full( long sql.id, long size )
Description
This sets the size of the RDBMS buffer. The buffer is used to send the result rows of a query from the database back to the client (that is, the bshell). For example, if a query fetches 20 rows and you have set the size of the buffer to 5, then the database sends the rows back to the client five at a time.
You call the function immediately after calling sql.parse().
Arguments
sql_id
The query ID, as returned by sql.parse().
size
The size of the buffer, in rows.
Return values
0 success
<>0 error
Context
Bshell function.
Functions reference
15-6
Dynamic SQL queries
Syntax
long sql.where.bind( long sql_id, long pseudo_var, var_name(.) )
Description
This binds a pseudo variable from the WHERE clause of a specified SQL query to a BAAN 4GL variable. This enables the BAAN 4GL variable to be used in the
WHERE clause. Note that there is no need to bind external variables.
Arguments
sql_id
The query ID, as returned by sql.parse().
pseudo_var
The pseudo variable from the WHERE clause. This is always a number. In the WHERE clause, it is entered as the number, prefixed by a colon [:].
var_name
The name of the BAAN 4GL variable to which the pseudo variable must be bound.
Return values
0 success
<>0 error
Context
Bshell function.
Example
string city(30) long sql_id city = "London" sql_id = sql.parse( "select tccom000.* " & "from tccom000 " &
"where tccom000.city = :1" ) sql.where.bind(sql_id, 1, city)
Functions reference
15-7
Dynamic SQL queries
Functions reference
15-8
Use these functions for handling enumerated domains and table fields.
domain ask.enum
string enum.descr$ long etol domain ltoe void void set.enum.values
set.enum.values.
for.field
( string quescode(10), domain default_enumvalue [, arg ] ... )
( string domain code(12), enum_expr
[, string language_code] )
( domain domain_value )
( long long_value )
( enum_constant, ... )
( const string field.name.string,
[ALL_ENUMS_EXCEPT], enum_value,
... )
Syntax
domain ask.enum( string quescode(10), domain default_enumval [, arg ] ... )
Description
This displays a message box containing a question and a number of possible responses. The responses are presented as push buttons. To respond to the question and close the message box, the user selects one of the push buttons.
The possible responses are defined in the data dictionary as an enumerated domain. By default, the function displays all of the defined enumerate values. To display a subset only, call set.enum.values() before calling ask.enum().
Functions reference
16-1
Enumerates
Arguments
quescode
The question to be displayed in the message box is defined in the data dictionary. This argument specifies the data dictionary code for the question.
If the question contains substitution symbols, use the third and subsequent arguments to specify the values to substitute for these symbols.
default_enumval
Specifies the enumerate value of the default answer. For example, yesno.yes
. If this argument is empty, the default value specified in the data dictionary is used.
arg, …
The values to substitute for any substitution symbols that the question contains. See sprintf().
Notes
The question text and the push button labels are always in the language of the user. The return value of ask.enum() is always the name of the enumerate value and not its description. So the script in which the function is used remains language independent.
After execution of ask.enum(), the standard variable attr.enum.mask$ is cleared. This also happens when the standard program calls ask.enum().
Return values
The value of the enumerated domain that corresponds to the option selected by the user. This is always the name of the enumerate value and not its description.
Context
3GL library function.
Example
This example assumes an enumerated domain ’yesno’ with two possible constants: ’yesno.yes’ and ’yesno.no’. It also assumes a question defined in the data dictionary with code "tccom00001". This question contains the string "Error
%d in file %s; Try again [y/n]?". The default answer is yes.
Functions reference
16-2
Enumerates
ret = seq.open( filename, "w" ) while ( ret <= 0 )
if ( ask.enum("tccom00001", yesno.yes, ret, filename )
= yesno.no) then
return
endif
ret = seq.open( filename, "w" ) endwhile
Syntax
string enum.descr$(string domain code(12), enum_expr [, string language_code ] )
Description
This returns the description associated with a specific value in an enumerated domain.
Arguments
code
The name of the domain. The domain must be of type enumerated.
One of the possible values of the enumerated domain.
enum_expr language_code
To retrieve the description in a language other than the user language, specify the relevant language code in this argument. This is an optional argument. The default language is the language of the user.
Note that the language code of the user is available in the predefined, read-only variable language$.
Return values
The description of the specified enumerate value, either in the current user language or in another specified language.
The function returns an empty string, and displays an error message, if an unknown domain is specified or if no description exists in the data dictionary for the specified language.
Functions reference
16-3
Enumerates
Context
Bshell function.
Example
This example assumes an enumerated domain ’yesno’ with two possible constants: ’yesno.yes’ and ’yesno.no’. It also assumes that 1 is the language code for Dutch, 2 is the language code for English, and 3 is the language code for
German. English is the current user language.
domain yesno active | enumerated domain string descr(25) active = yesno.no
descr = enum.descr$("yesno", active, "1")
| descr contains "nee" descr = enum.descr$("yesno", active)
| descr contains "no" descr = enum.descr$("yesno", active, "3")
| descr contains "nein"
Syntax
long etol( domain domain_value )
Description
This returns the numeric code corresponding to a specified value in an enumerated domain.
Context
Bshell function.
Example
See ltoe().
Functions reference
16-4
Enumerates
Syntax
domain ltoe( long long_value )
Description
This returns the named constant corresponding to a specified numeric code. The numeric code represents one of the values in an enumerated domain.
Example
This example assumes an enumerated domain ’yesno’ with two possible constants: 'yesno.yes’ (=1) and 'yesno.no’ (=2).
domain yesno active long enum_long active = yesno.no
enum_long = etol( active ) | enum_long now contains 2 active = ltoe( 1 ) | active now equals yesno.yes
Syntax
void set.enum.values( enum_constant, ... )
Description
This fills the predefined variable attr.enum.mask$ with a specified set of enumerate values. This is useful for restricting the values valid for the
Notes
In the case of enumerated fields, use set.enum.values.for.field().
After execution of ask.enum(), the variable attr.enum.mask$ is cleared again.
This also happens when the standard program calls ask.enum().
Context
3GL library function.
Functions reference
16-5
Enumerates
Syntax
void set.enum.values.for.field( const string field.name.string, [ALL_ENUMS_EXCEPT], [ enum_value,
... ] )
Description
This fills a listbox field with a specified set of enumerate values.
With set.enum.values(), the change to a set of enumerate values occurs immediately before input to the enumerated field. With
on which the change depends become true. To achieve this, include the function in the before.display.object section or in the when.field.changes section of each field on which the change depends.
Arguments
field.name.string
ALL_ENUMS_EXCEPT This optional macro specifies that the succeeding list of enumerate values represents those values that are to be excluded from the enumerate set.
Otherwise, the list of enumerate values represents the values that are to be included.
enum_value, …
The name of the enumerated field. For example,
"ttadv996.type". For an array field, include the array element. For example, "tttadv996.type(5)".
The values to be displayed in the field, separated by commas [,].
This is an optional argument. If not included, all enumerate values defined for the field are available.
Notes
You can set enumerate values for the current occurrence only.
If the existing value of an enumerated field in not included in the new set, no value is selected in the list and no value is displayed in the display area of the listbox.
Functions reference
16-6
Enumerates
Context
4GL library function.
Example
field ttadv996.fld1: when.field.changes: if ttadv996.fld1 < SOME_VALUE then set.enum.values.for.field(ttadv996.type, ttadv.ktex.session, ttadv.ktex.form, ttadv.ktex.domain)
| no value is selected if the current value of
| ttadv996.type is not in the new set!
else set.enum.values.for.field(ttadv996.type)
| all enum items are available endif
Functions reference
16-7
Enumerates
Functions reference
16-8
Use these functions for handling events.
Event-driven programs, such as BAAN 3GL scripts, are designed to respond to events. Usually, they consist of a main loop that waits for events to occur. When an event occurs, the program performs the appropriate actions to process the event. It then returns to its waiting state.
Most of the events that occur in a BAAN application relate to user interaction.
When a user performs an action in the user interface (for example, clicking the mouse or pressing a keyboard key), this generates an event. The event consists of a package of information about the particular action. It is delivered to the event queue of the relevant process group and from there to the individual process that will handle the event. When the process retrieves the event from the event queue, it executes the piece of code appropriate for processing the particular type of event received.
Note that the event package takes the form of an array of longs. You retrieve the individual items of information in the array by using a set of parameters specific to the event type.
The event paradigm is used in both ASCII and graphical programming environments. But some events are relevant only in graphical environments (for example, mouse events).
For further information on user interface controls and process groups, see
Chapter 5, User interface objects, and Chapter 31, Process groups.
long long long void long next.event
peek.event
pending.events
( [long event(EVTMAXSIZE)] )
( [long event(EVTMAXSIZE)] )
( ) select.event.input
( long object_id, long masks ) send.event
( long proc_grp, long event(EVTMAXSIZE) )
Functions reference
17-1
Events
Syntax
long next.event( [long event(EVTMAXSIZE)] )
Description
This removes the event at the top of the event queue and stores it in event. If the event queue is empty, the function waits (that is, it is blocked) until an event arrives. To time out the next.event() function, use set.timer().
Arguments
event(EVTMAXSIZE) An array of longs containing details of the event. You retrieve the contents of the event array by using a set of parameters specific to the event type. See “Event array parameters” in Chapter 17.
The EVTMAXSIZE constant indicates the number of elements in the array.
Return values
The event type. See “Event types” later in this chapter.
Context
Bshell function.
Example
long event(EVTMAXSIZE), object_id select.event.input( object_id, EVTBUTTONPRESSMASK +
EVTBUTTONRELEASEMASK + EVTKEYPRESSMASK +
EVTBUTTONMOTIONMASK ) next.event( event ) on case evt.type( event ) case EVTBUTTONPRESS:
...
case EVTKEYPRESS:
...
default:
...
endcase
Functions reference
17-2
Events
Syntax
long peek.event( [long event(EVTMAXSIZE)] )
Description
This reads the event at the top of the event queue and stores it in event. It does not remove the event from the queue. If the event queue is empty, the function waits (that is, it is blocked) until an event arrives. To time out the peek.event() function, use set.timer().
Arguments
event(EVTMAXSIZE) An array of longs containing details of the event.
You retrieve the contents of the event array by using a set of parameters specific to the event type. See
“Event array parameters” in Chapter 17.
The EVTMAXSIZE constant indicates the number of elements in the array.
Return values
The event type. See “Event types” later in this chapter.
Context
Bshell function.
Example
long event(EVTMAXSIZE), object_id select.event.input( object_id, EVTBUTTONPRESSMASK +
EVTBUTTONRELEASEMASK + EVTKEYPRESSMASK +
EVTBUTTONMOTIONMASK ) while peek.event() = EVTBUTTONMOTION next.event( event )
....
endwhile
Functions reference
17-3
Events
Syntax
long pending.events()
Description
This returns the number of events present in the event queue of the process group. Note that including the function in an empty loop uses a lot of processor time. For example: while not pending.events() endwhile
Return values
>0
0 number of events in event queue empty queue
Context
Bshell function.
Example
long event if pending.events() > 0 then next.event( event ) else
....
endif
Syntax
void select.event.input( long object_id, long masks )
Description
This defines which event types can be generated by the specified object.
Functions reference
17-4
Events
Arguments
object_id
The ID of the object to which the specified masks apply.
masks
A combination of one or more values that indicate the event types that the specified object can generate.
If the event queue already contains events not specified by this function, they are NOT removed from the queue.
The possible event mask values are:
EVTNOEVENTMASK
EVTALLEVENTMASK
EVTBUTTONPRESSMASK events
EVTBUTTONDPRESSMASK press
No events
All events
Mouse button press
Mouse button double events
EVTBUTTONRELEASEMASK Mouse button release events
EVTBUTTONMOTIONMASK Mouse pointer motionevents
EVTKEYPRESSMASK events
Key press
EVTRESIZEWINDOWMASK Resize window events
EVTBUTTONSELECTMASK Control button select events
EVTFIELDSELECTMASK events
Field select
EVTGRIDEVENTMASK Grid events
EVTLISTBOXSELECTMASK List box item select events
EVTMENUSELECTMASK events
Menu item select
EVTSCROLLBARSELECTMASK Scrollbar select events
EVTTABSELECTMASK Tab frame events
EVTTREESELECTMASK
EVTCHANGEFOCUSMASK
EVTSETFOCUSMASK
Tree events
Change focus events
Set focus
Functions reference
17-5
Events
events
EVTIOEVENTMASK
EVTOLEEVENTMASK
EVTTERMINATIONMASK
EVTHELPEVENTMASK
I/O events
OLE events
Termination events
Help events
Notes
Events of type EVTCLIENTMESSAGE, EVTBUCKETMESSAGE, and
EVTTIMEREVENT are always selected.
You cannot add to the currently selected events by calling select.event.input() with the additional masks. You must specify all required event masks each time you call the function.
Context
Bshell function.
Example
long object_id select.event.input( object_id, EVTBUTTONPRESSMASK +
EVTKEYPRESSMASK )
Syntax
long send.event( long proc_grp, long event(EVTMAXSIZE) )
Description
This sends an event from the current process to the specified process group. It enables event-driven communication between processes. A process can send any event type using this function. Note that this is the only way to send events of type EVTCLIENTMESSAGE.
If the sending process requires an immediate response, use suspend(0) to force a context switch; that is, to force the system to give processor time to the destination process.
Functions reference
17-6
Events
Arguments
proc_grp
The ID of the process group.
event
The event that must be sent to the process group. For details of the content of the event array, see “Event array parameters” in
Chapter 17.
Return values
TRUE success
FALSE error
Context
Bshell function.
Example
This example sends a message that indicates the start of sending.
#define START_SEND 1 long process, event(EVTMAXSIZE) evt.type( event ) = EVTCLIENTMESSAGE evt.client.sender( event ) = pid evt.client.command( event ) = START_SEND if not send.event( get.pgrp(process), event ) then message( "Process %d is not responding", process ) endif
The following section lists all available event types and describes their context.
EVTBUTTONPRESS Occurs when a mouse button is pressed.
EVTBUTTONDPRESS
EVTBUTTONRELEASE
Occurs when a mouse button is double pressed.
Occurs when a mouse button is released after being pressed.
EVTBUTTONMOTION
EVTKEYPRESS
Occurs when the mouse is moved while at least one mouse button is pressed.
Occurs when a keyboard key is pressed.
Functions reference
17-7
Events
EVTRESIZEWINDOW
EVTBUTTONSELECT
EVTFIELDSELECT
EVTGRIDEVENT
EVTLISTBOXSELECT
Occurs when a main window (DsCmwindow) is resized.
Occurs when a control button is selected.
Examples of control buttons are push buttons
(DsCpushButton), check boxes
(DsCcheckBox), option buttons
(DsCradioButton), toolbar buttons
(DsCtoolBar), and drawn buttons
(DsCdrawnButton).
Occurs when a new value is entered in an edit field (DsCfield).
Occurs when a grid control (DsCgrid) is modified.
Occurs when one or more items are selected in a combo box (DsCcomBox), a drop-down combo box (DsCdDComBox), a drop-down list box (DsCdDListBox), or a list box
(DsClistBox).
EVTMENUSELECT Occurs when a menu item is selected in a bar menu object (DsCbarMenu).
EVTSCROLLBARSELECT Occurs when a scrollbar (DsCscrollbar or
EVTTABSELECT Occurs when a tab is selected in a tab frame control (DsCtabFrame).
EVTTREESELECT
EVTCHANGEFOCUS
EVTSETFOCUS
Occurs when an item in a tree control
(DsCtree) is expanded, collapsed, or selected.
Occurs when the keyboard focus is moved. The user can move the focus from one object to another by pressing the TAB key or an arrow key.
Occurs when an object receives keyboard focus by the user clicking on it with the mouse.
EVTIOEVENT Occurs when data is available on a socket, when a connection request is pending on a socket, and when an I/O error occurs on a socket.
Functions reference
17-8
Events
EVTOLEEVENT
EVTTERMINATION
EVTHELPEVENT
EVTBUCKETMESSAGE
EVTCLIENTMESSAGE
EVTTIMEREVENT
Occurs when some action is performed on an
OLE object in a graphical window
(DsCgwindow). Only BAAN Windows can generate this event.
Occurs when a Windows application started by
BAAN Windows (Notepad, for example) terminates. Only BAAN Windows can generate this event.
Occurs in response to a request for help on a user interface object.
Occurs when a process sends a bucket message, using bms.send().
Occurs when a process sends a client message, using send.event().
Occurs when a timer sends an event.
The event argument included in next.event(), peek.event(), and send.event() consists of an array of longs that contain details of the incoming or outgoing event. You retrieve the contents of an event array by using the set of parameters defined for the particular event type. These parameters are listed below, by event type.
All events
evt.type( event ) evt.window( event )
The event type.
The ID of the object that generated the event.
Functions reference
17-9
Events
Mouse button events
EVTBUTTONPRESS, EVTBUTTONDPRESS, and EVTBUTTONRELEASE evt.button.x( event ) evt.button.y( event )
X-position of mouse action in window.
Y-position of mouse action in window.
evt.button.state( event ) Indicates which modifier keys are held down when the mouse button is pressed. Possible values are:
EVTSHIFTMASK
EVTCONTROLMASK
EVTBUTTON1MASK
EVTBUTTON2MASK
EVTBUTTON3MASK evt.button.button( event ) Indicates which mouse button is pressed. Possible values are:
EVTBUTTON1 left mouse button
EVTBUTTON2 middle mouse button
EVTBUTTON3 right mouse button evt.button.rootx( event ) evt.button.rooty( event )
Absolute x-position of mouse action on desktop.
Absolute y-position of mouse action on desktop.
Mouse motion events
EVTBUTTONMOTION evt.motion.x( event ) evt.motion.y( event )
X-position of mouse pointer in window during motion.
Y-position of mouse pointer in window during motion.
evt.motion.state( event ) Indicates which modifier keys are held down while the mouse pointer is moved. Possible values are:
EVTSHIFTMASK
EVTCONTROLMASK
EVTBUTTON1MASK
EVTBUTTON2MASK
EVTBUTTON3MASK
Functions reference
17-10
Events
evt.motion.rootx( event ) Absolute x-position of mouse pointer on desktop during motion.
evt.motion.rooty( event ) Absolute y-position of mouse pointer on desktop during motion.
Keypress events
EVTKEYPRESS evt.keypress.key( event ) evt.keypress.state( event )
ASCII or TSS value of pressed key.
Indicates which modifier keys are held down while the key is being pressed. Possible values are:
MOD_CTRL
MOD_SHIFT
MOD_ALT
Window resize events
EVTRESIZEWINDOW evt.resize.columns( event ) evt.resize.rows( event ) evt.resize.width( event ) evt.resize.height( event )
New width in number of columns (character window).
New height in number of rows (character window).
New width in pixels (graphical window).
New height in pixels (graphical window).
Control button events
EVTBUTTONSELECT evt.button.return( event ) Return value of the button, where relevant.
evt.button.checkstate( event ) The state of toolbar buttons, check boxes and option buttons. Possible values are:
EVTBUTTONCHECKED button pressed or checked
EVTBUTTONUNCHECKED button released or unchecked
Functions reference
17-11
Events
Field select events
EVTFIELDSELECT
There are no parameters specific to these event types. See “All events” earlier in this chapter.
Grid events
EVTGRIDEVENT evt.grid.row( event ) evt.grid.column( event ) evt.grid.width( event ) evt.grid.height( event ) evt.grid.range.left( event ) evt.grid.range.top( event ) evt.grid.range.right( event )
Row index (1-based index).
Column index (1-based index).
Column width.
Row height.
Index of leftmost column of range.
Index of topmost row of range.
Index of rightmost column of range.
evt.grid.range.bottom( event ) Index of bottommost row of range.
evt.grid.selmark( event ) Mark state of a selection. Possible values are:
DSGRIDMARKNONE nothing marked
DSGRIDMARKNEW new mark
DSGRIDUNMARK
DSGRIDADDMARK add mark unmark
Functions reference
17-12
evt.grid.reason( event )
Events
The action that caused the event. Possible values are:
EVTGRIDCHANGEDATA data changed
EVTGRIDCHANGEFOCUS internal focus moved to another cell
EVTGRIDACTIVATE selection activated by double-click
EVTGRIDFOCUSCHANGEDBYMOUSE internal focus moved to another cell by mouse click
EVTGRIDMARKRANGE range selected
EVTGRIDMARKCELL cell selected
EVTGRIDMARKROW row selected
EVTGRIDMARKCOLUMN column selected
EVTGRIDRESIZEROW row height changed
EVTGRIDRESIZECOLUMN column width changed
EVTGRIDMOVEROW row moved
EVTGRIDMOVECOLUMN column moved
EVTGRIDBUTTONPRESS control button pressed
EVTGRIDLISTBOXSELECT item selected in list box
EVTGRIDRESETSELECTION all rows, columns, cells unselected
Functions reference
17-13
Events
The value of the evt.grid.reason parameter determines which of the other parameters are included as part of the event. For example, if the event reason is
EVTGRIDRESIZEROW, then evt.grid.row and evt.grid.height must be included in the event. Similarly, if the event reason is
EVTGRIDMARKRANGE, then evt.grid.range.left, evt.grid.range.top,
List box item select events
EVTLISTBOXSELECT evt.listbox.item_id( event ) evt.listbox.reason( event )
ID of the selected list-box item.
The action that caused the event. Possible values are:
EVTLISTBOXREASONTEXT text typed in edit field of combo box
EVTLISTBOXREASONACTIVATE item double-clicked
EVTLISTBOXREASONSELECTION selection changed evt.listbox.selcount( event ) Number of selected items.
Menu item select events
EVTMENUSELECT evt.menu.return( event ) ID of the selected menu item.
Scrollbar select events
EVTSCROLLBARSELECT evt.scrollbar.action( event ) The action that caused the event. Possible values are:
SBUP SBDOWN
SBPRESS SBMOVE
SBRELEASE
SBPGUP
SBPGDOWN
SBHOME SBEND
Functions reference
17-14
Events
evt.scrollbar.value( event )
Tab frame events
EVTTABSELECT evt.tab.index( event )
Current position in scrollbar.
Index of selected tab (1-based index)
Tree events
EVTTREESELECT evt.tree.item_id( event) ID of the tree item that caused the event.
evt.tree.reason( event ) The action that caused the event. Possible values are:
EVTTREEREASONACTIVATE leaf in tree activated
EVTTREEREASONEXPAND tree node expanded
EVTTREEREASONCOLLAPSE tree node collapsed
EVTTREEREASONSELECT tree item selected
Change focus events
EVTCHANGEFOCUS and EVTSETFOCUS evt.focus.object( event ) The object that currently has keyboard focus
(EVTCHANGEFOCUS).
The object that has received keyboard focus
(EVTSETFOCUS).
evt.focus.key( event ) Indicates the key that caused an
EVTCHANGEFOCUS event. Possible values are:
KEY_TAB
KEY_UP
KEY_RIGHT
KEY_HOME
KEY_PGUP
KEY_BACKTAB
KEY_DOWN
KEY_LEFT
KEY_END
KEY_PGDOWN
Functions reference
17-15
Events
I/O events
EVTIOEVENT event.array(1) The event type. This is always EVTIOEVENT.
event.array(2) The reason that the event was sent. Possible values are:
EVTSOCKHASDATA data is available on the socket specified in event.array(3)
EVTSOCKIOERROR error occurred on the socket specified in event.array(3)
EVTCONNECTREQUEST connection request is pending on the socket specified in event.array(3) event.array(3) The file pointer of the relevant socket.
OLE events
EVTOLEEVENT evt.ole.event( event ) The OLE event type. Possible values are:
EVTOLECREATEINSTANCE
EVTOLESETHOSTNAMES
EVTOLESHOWWINDOW
EVTOLEHIDEWINDOW
EVTOLELOADDATA
EVTOLESAVEDATA
EVTOLECLOSE
EVTOLELOCKSERVER
EVTOLEUNLOCKSERVER
EVTOLEDATACHANGED
EVTOLERELEASED
EVTOLEAUTOMATION
EVTOLESHOWOBJECT
EVTOLEOBJECTWINDOWVISIBLE
EVTOLEOBJECTWINDOWINVISIBLE class factory wants to create an object request hostnames request to make object visible request to make object invisible request to load an embedded object with data request to save an embedded object server closes embedded object set lock to keep application running reset lock embedded object data has changed all references to object released automation request to call DLL function request to scroll embedded object in view object in running mode object not in running mode
Functions reference
17-16
Events
evt.ole.size( event ) evt.ole.subobject( event )
For a data change or data save event, this stores the size of the data.
If the OLE object is an embedded object, displayed in a graphical window (DsCgwindow), this indicates the ID of the graphical subobject in the gwindow.
Application termination events
EVTTERMINATION evt.termination.reason( event ) The action that caused the event. Possible values are:
DSTerminationSetDir
DSTerminationOpenStdin
DSTerminationOpenStdout
DSTerminationOpenStderr
DSTerminationCreateProcess
DSTerminationCreateThread
DSTerminationNormalExit evt.termination.exitcode( event ) The application’s exit code.
Help events
EVTHELPEVENT evt.help.return( event ) Return value of the control button, toolbar button, or menu option for which help is requested. This is
-1 for all other object types.
evt.help.row( event ) Grid row index if help requested for a grid object.
This is -1 for all other object types.
evt.help.column( event ) Grid column index if help requested for a grid object. This is -1 for all other object types.
evt.help.reason( event ) EVTHELPCOMMAND help requested using F1
EVTHELPCONTEXT help in context-sensitive help mode
Functions reference
17-17
Events
Client events
EVTCLIENTMESSAGE evt.client.sender( event ) Process ID of sender.
evt.client.command( event ) Application-specific command code.
evt.client.argument( event ) Application-specific argument.
Bucket message events
EVTBUCKETMESSAGE evt.bms.sender( event ) evt.bms.command( event ) evt.bms.argument( event )
Process ID of sender.
Application-specific command code.
Application-specific argument.
Timer events
EVTTIMEREVENT evt.timer.id( event) ID of timer that sent the event.
Functions reference
17-18
Events
long event(EVTMAXSIZE) while TRUE next.event(event) on case evt.type(event) case EVTKEYPRESS: on case evt.keypress.key(event) case KEY_RETURN:
....
case KEY_ESC:
....
break
endcase
break case EVTCHANGEFOCUS: on case evt.focus.key(event) case KEY_TAB: case KEY_DOWN:
| set focus on next field case KEY_BACKTAB: case KEY_UP:
| set focus on previous field endcase break case EVTBUTTONSELECT: if ( evt.button.return(event) = ABORT.BUTTON ) then
| ABORT.BUTTON is the return value of the
| button pressed return endif break endcase endwhile
Functions reference
17-19
Events
Functions reference
17-20
Use these functions to compile and evaluate expressions at runtime. This is particularly useful when expressions or formulas are stored in a database or can be entered by a user.
Use of these functions increases system load and should be avoided, where possible.
double long void long string d.expr
expr.compile
expr.free
l.expr
s.expr$
( long expr_id [, arg] )
( "expression" )
( long expr_id )
( long expr_id [, arg] )
( long expr_id [, arg] )
Syntax
double d.expr( long expr_id [, arg] )
Description
Executes (or evaluates) an expression previously compiled by expr.compile. The result is always converted to a double.
Arguments
expr_id
The ID of the compiled expression, as returned by expr.compile.
arg
If the expression contains the characters ’$$’, the value specified by this argument is substituted for those characters. This is an optional argument.
Functions reference
18-1
Expressions (runtime)
Note
You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.
Return value
The result of the expression converted to a double.
Context
Bshell function.
Syntax
long expr.compile( "expression" )
Description
This compiles the specified expression and returns an ID number for the compiled expression. The expression can be executed subsequently using
must be know at runtime, they must be declared as external variables.
You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.
Notes
The expression can include any of the following features: n
An assignment, specified by using := . For example:
("a:=3") n
Merged expressions, separated by commas (,). For example:
("a:=3, b:=7, c-8") n
Operators. These have the same function as in normal expressions. Integer division is an exception. Normally, integer division returns an integer (for example, 45/30 returns 1). With these functions, integer division returns a double (for example, 45/30 returns 1.5).
n
The IN keyword. Use this to check whether a value lies within a specified range.
Functions reference
18-2
Expressions (runtime)
n
The following constants: n
PI ( = 3.1415927... )
TRUE
FALSE
Conditional expressions. For example:
("a:= (a) ? 0 : a") n
Numerical ranges. For example:
("a IN [12,30]")
or
("a IN [12,30] [50,100] [200,500]") n
In expressions on forms, you can use the following characters:
$$ represents the current field name
$# represents the current domain name n
For example:
"$$ IN [30,40]"
The following functions: abs() acos() asc() asin() atan() chr() cos() cosh() edit() exp() int() len() log() log10() max() min() pos() pow() round() rpos() sin() sqrt() str() strip() tan() tanh() val() time() date() current time in HHMM format current date in number of days since January 1, 0001 date(YYYY,MM,DD) date constant – for example:
(
"date() IN [ date(1988,1,1), date(1992,1,1) ]") utc() current date and time in UTC long format utc(YYYY,MM,DD,HH,MM,SS) specified local date/time in UTC long format fmin() fmax() returns the minimum value of a 4GL variable, domain, or table field returns the maximum value of a 4GL variable, domain, or table field n
String regular expressions. These are string constants which can contain the following characters:
^ means the beginning of the string
$ means the end of the string
Functions reference
18-3
Expressions (runtime)
character
*
[] takes the previous character 0 or more times means one of the characters between [] – for example:
[abcd123] or [a-z] or [a-zA-Z]
[^] means any character except the characters after ^
"" means a double quote within a string
The result of a regular expression that includes IN is 0 if the expression is
FALSE. If the expression is TRUE, the result is a long containing 4 bytes.
The first two bytes contain the length of the substring; the last 2 bytes contain the position of the substring in the string.
3
"abcdefg" IN "def"
"abcdefg" IN "^def$"
"abcdefg" IN "^[a-z]*$"
"abcdefg" IN "^a"
"abcdefg" IN "^b"
"abcdefg" IN "g$"
"abcdefg" IN "^a.*g$"
"abcdefg" IN "^[^a].*"
"abcdefg" IN "^[^b-z]"
1
7
7
1
1
4
FALSE
1
1
FALSE
7
1
FALSE
1
You can retrieve the length and position from the result with store.long() and
long string expr_id, lng, length_res, pos_res tmp(4) expr_id = expr.compile( """abcdefg"" IN ""def""" ) lng = l.expr( expr_id ) store.long( lng, tmp ) length_res = load.short( tmp(1;2) )|length_res contains 3 pos_res = load.short( tmp(3;2) ) |pos_res contains 4
Return value
An ID for the compiled expression.
Context
Bshell function.
Functions reference
18-4
Expressions (runtime)
Syntax
void expr.free( expr_id )
Description
This frees the memory allocated to a compiled expression. expr_id is the ID of the compiled expression, as returned by expr.compile. It is important to call this function when you have finished with an expression.
Context
Bshell function.
Syntax
long l.expr( long expr_id [, arg] )
Description
Executes (or evaluates) an expression previously compiled by expr.compile. The result is always converted to a long.
Arguments
expr_id
The ID of the compiled expression, as returned by expr.compile.
arg
If the expression contains the characters ’$$’, the value specified by this argument is substituted for those characters. This is an optional argument.
Note
You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.
Return value
The result of the expression converted to a long.
Functions reference
18-5
Expressions (runtime)
Context
Bshell function.
Syntax
string s.expr$( long expr_id [, arg] )
Description
Executes (or evaluates) an expression previously compiled by expr.compile. The result is always converted to a string.
Arguments
expr_id
The ID of the compiled expression, as returned by expr.compile.
arg
If the expression contains the characters ’$$’, the value specified by this argument is substituted for those characters. This is an optional argument.
Note
You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.
Return value
The result of the expression converted to a string.
Context
Bshell function.
Functions reference
18-6
Use these functions to perform form and form field operations. For example: n n n n n n n n n n n
To disable and enable commands and fields
To display particular fields
To update total fields
To execute a function for one or all occurrences on a form
To execute standard commands
To display default field values
To make fields visible or invisible
To mark and unmark occurrences
To display fill characters in fields
To refresh the current record
To reset a field to its previous value
void add.view.field
void long void void void void blank.all
change.field.label
check.all.input
choice.again
disable.commands
disable.fields
void void void void void display display.all
display.curr.occ
display.fld
display.occ
( long index.nr, const string fname )
( )
( const string fname, long element, const string smes)
( )
( )
( string command [, string command]... )
( [ long mode,] string field
[, occurrence] [, string field [, occurrence]]... )
( field )
( )
( )
( long occurrence, field )
( long occurrence )
Functions reference
19-1
Form and form field operations
void void void void void void void void void void void long void long void void void void void void void void void void void long void display.total.fields
do.all.occ
do.occ
( string fieldname1, long value1 [, string fieldname2, long value2]
... )
( function_name [, ...] )
( long occurrence, function_name [, ...] ) do.occ.without.update
( long occurrence, function_name [, ...] ) enable.commands
( string command [, stringcommand]... ) enable.fields
execute get.field.label
( string field [, string field]... )
( long command )
( const string fname, long element, ref string label1 mb, ref string label2 mb, ref string label3 mb )
( ) get.screen.defaults
group.invisible
input.again
inputfield.invisible
inputfield.password
inputfield.visible
( long group.nr )
( )
( string field_name(18) [, string field_name(18)]...)
( string field_name(18) [, string field_name(18)]...)
( string field_name(18) [, string field_name(18)]...)
( string field_name(18) ) is.field.invisible
make.current
mark.occ
on.old.occ
print.const
refresh.curr.occ
( )
( long occurrence )
( function_name [, ...] )
( [string fill_string(127)] )
( ) remove.mark
set.fields.default
stp.reset.value
to.field
to.form
to.group
update.occ
( )
( )
( )
( field )
( long form_number )
( long group.nr )
( )
Functions reference
19-2
Form and form field operations
Syntax
void add.view.field( long index.nr, const string fname )
Description
The view fields for a dynamic session are determined by the view column in the
Available Indices by Session session. Dependent child fields of the index fields are also displayed. You use this function to add a view field that is not part of the index and that is not a child field of one of the index fields.
Arguments
index.nr
The index identifier. If this is 0, the field is not associated with any index. It is always a view field.
fname
The name of the form field to be added. To specify a particular element of an array field, append the element number (in parentheses) to the field name. For example:
"ttadv301.labl(2)" .
Context
4GL library function.
You can use this function only in the before.program section of 4GL scripts.
Syntax
void blank.all()
Description
This clears all display fields and input fields on the current form. Display only and input only fields (that is, display and input fields that are not included in the form’s TAB sequence) are not cleared.
Context
4GL library function.
Functions reference
19-3
Form and form field operations
You can use this function only in 4GL scripts. You must also use it only in combination with the standard program.
Syntax
long change.field.label( const string fname, long element, const string smes )
Description
Use this to set the label text for a specified field. A field label can consist of up to three lines of text. However, you can set only a single line of text with this function. The new label replaces the entire existing label.
This function is relevant to dynamic forms only.
Arguments
fname
The name of the field whose label must be set.
element
For an array field, use this to specify the array element for which you want to set the label.
smes
The new label text.
Return values
0
-1
-2 success session is not dynamic field not found
Context
4GL library function.
Functions reference
19-4
Form and form field operations
Syntax
void check.all.input()
Description
This executes all check.input subsections (if any) included in the program script.
When an input error is detected, the choice.again() function is automatically executed. If a check.input subsection is included for an array field, it is executed for each element in the array.
When a DAL is used, the property checks in the DAL are executed after the
Context
4GL library function.
The standard program automatically calls this function before saving a record in the database. Application programmers can include this function only in
Example
choice.cont.process: before.choice: check.all.input()
Syntax
void choice.again()
Description
This cancels execution of a standard command and transfers control to the standard program. Statements programmed after this function will never be executed. You can call this function during execution of a standard command.
You can also call the function in field sections, as these are called indirectly during execution of some commands.
Functions reference
19-5
Form and form field operations
Context
4GL library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections: before.choice, on.choice, after.choice
before.field, before.input, on.input, after.input, when.field.changes, after.field
Example
field.pctst999.item: after.input: if pctst999.item = 99999 then mess("pctst.0001",1) choice.again() endif
| Modifying a record with item = zero is not allowed choice.modify.set: before.choice: if pctst999.item = 0 then mess("pctst.0002",1) endif choice.again()
Syntax
void disable.commands( string command [, string command]... )
Description
This disables the specified standard and/or form command(s). Standard commands are identified by their command IDs. Form commands are identified either by a function name, a session code, or a menu code.
Note
The standard program can enable and disable form commands depending on the number of occurrences currently selected in the form.
Functions reference
19-6
Form and form field operations
Context
4GL library function.
Example
disable.commands( "test.function", "ttadv3500m000", ADD.SET )
Syntax
void disable.fields( [ long mode,] string field [, occurrence] [, string field [, occurrence] ... )
Description
This disables single-occurrence and multioccurrence fields on a form.
Arguments
mode
This is an optional argument. It has two possible values:
DISABLE
This is the default mode and does not need to be specified.
READONLY
The field(s) become read-only fields that cannot be edited by the user.
Functions reference
19-7
Form and form field operations
field
[,occurrence]
This identifies the field to be disabled.
For a single-occurrence field, this is the field name. For a multioccurrence field, this can be either the field name or the field name followed by an occurrence number
(depending on whether you wish to disable all occurrences of the field or only one particular occurrence).
For array fields, UTC fields, and segmented fields, you can append suffixes to the field name to indicate the particular element or segment to be disabled. If you omit these suffixes, all elements/segments are disabled.
n
To disable a particular element of an array field, append the element number (in parentheses) to the field name.
The element number must be an integer, formatted as a string. It cannot be a variable. For example:
"tfmod100.perd(10)"
.
n
To disable only the date or time element of a UTC field, append either .date or .time to the field name. For example:
"ttadv300.cdat.time"
.
n
To disable a particular segment of a segmented field, append .segment.segment_id to the field name. For example:
"tiitm001.item.segment.1"
.
Context
4GL library function.
You can use the function in the following 4GL sections: before.display and
disable fields after the data has been read from the database but before the fields are displayed on the form. Include it in the when.field.changes section if you want to disable certain fields whenever the content of a related field changes.
Examples
| Disable two named single-occurrence fields disable.fields( "tccom010.beca", "tccom010.dsca" )
| Change to read-only fields the current occurrences of the
| multi-occurrence fields tccom010beca and tcccom101.dsca
disable.fields( READONLY, "tccom010.beca", actual.occ,
"tccom010.dsca", actual.occ )
Functions reference
19-8
Form and form field operations
| Disable element number 10 of an array field disable.fields( "tfmod100.perd(10)" )
| Disable elements 1 to 12 of an array field for i = start to 12 disable.fields( "month(" & str$(i) & ")" ) endfor
| Disable the date element of a UTC field ttaad500.fidt = 0 disable.fields( "ttaad500.fidt.date" )
| Disable the first and second segments of a segmented field disable.fields( "tcibd001.dfit.segment.1",
"tcibd001.dfit.segment.2")
Syntax
void display( field ) void display.all() void display.curr.occ() void display.fld( long occurrence, field ) void display.occ( long occurrence )
Description
Use these functions to display specified fields on a form. Usually, the standard program displays fields automatically, either when the form is opened or when data in a related input field is changed. However, there are situations when you need to use these functions to display fields. For example, to display stand-alone fields, to display fields that are not in the input field TAB sequence, or to send data to the form during batch processes.
display()
Displays a single-occurrence field. You cannot use this to display a field for all occurrences.
display.all()
Displays all fields of all occurrences.
display.curr.occ()
Displays all fields of the current occurrence.
Functions reference
19-9
Form and form field operations
display.fld() display.occ()
Displays a specified field of a specified occurrence. To display a field for all occurrences, use the following construction: for i= 1 to filled.occ
display.fld( i, field ) endfor
Displays all fields of a specified occurrence.
Arguments
field
Indicates the field to be displayed. This can be the field number or a string containing the field name. For example: display( "pctstqqq.item" ) display( 5 ) display.fld( actual.occ, "pctstqqq.item" )
occurrence
The occurrence for which the field(s) are to be displayed. You can use the predefined variable actual.occ here. This always contains the number of the current occurrence.
Notes
These functions always display the current value of the specified fields.
The current field pointer and form status are always saved when a display function is called and then restored when the function has terminated.
Non-database fields must be declared as extern in the program script.
The functions display.fld(), display.occ(), and display.curr.occ() are valid only for forms of type 2 or 3 (multioccurrence).
The functions display.all(), display.occ(), and display.curr.occ() do not affect stand-alone fields. To display a value for a stand-alone field use display() or
Context
4GL library functions.
You can use these functions only in 4GL scripts. You cannot use them in a
recursion, do not use the functions in before.display and after.display subsections of the same field.
Functions reference
19-10
Form and form field operations
Syntax
void display.total.fields( string fieldname1, long value1
[, string fieldname2, long value2 ] ... )
Description
When a total line is included in a form, this function displays total values for specified fields in the grid. The function takes one or more pairs of arguments. In each pair, the first argument is the field name; the second argument is the total value for that field.
The fields must be defined on the form as multioccurrence form fields. They must also be declared in the UI script. Alternately, the fields can be table fields.
To add a total line to a grid, add the following code to the UI script: before.program: fattr.total.line = true
Then for every update that effects the total fields, call display.total.fields() to display the new totals.
The total line can display an enum value. To do this, the description of the enum must be passed using enum.descr$() . For example: display.total.fields( "tffbs.dbcr", enum.descr$( "tfgld.dbcr", tfgld.dbcr.debit ) )
Notes
Total fields are always read-only. They cannot be disabled or enabled.
Total fields have the same display properties as the fields above them.
If a field specified by the function is an array field, the total value is displayed in the first field of the array. Subsequent fields in the array cannot be addressed by the function.
Context
4GL library function.
Functions reference
19-11
Form and form field operations
Example
before.program: fattr.total.line = true choice.first.set: after.choice: display.total.fields( "whwmd000.amnt1", tot_1,
"whwmd000.amnt2", tot_2 )
Syntax
void do.all.occ( function_name [, ... ] )
Description
This executes the specified function for all occurrences on the current form.
When included in the before.choice subsection of a choice.update.db section, the function is executed only for updated occurrences.
Arguments
function_name
The name of the function that must be executed. The function must be of type void.
...
Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Context
4Gl library function.
You can use this function only in 4GL scripts, of types 1, 2, and 3. You can use it in the following event subsections: before.choice, on.choice, after.choice
before.input, on.input, after.input, check.input
when.field.changes, before.zoom, after.zoom
See also
do.occ(), do.occ.without.update(), on.old.occ()
Functions reference
19-12
Form and form field operations
Example
declaration: long old_inventory choice.cont.process: on.choice: do.all.occ( update_occurrences, 9999 ) main.table.io: before.rewrite: on.old.occ( get_old_inventory ) pctst999.change = pctst999.item - old_inventory functions: function void update_occurrences( long new_val )
{ pctst999.special = new_val
} function void get_old_inventory()
{ old_inventory = pctst999.item
}
Syntax
void do.occ( long occurrence, function_name [, ...] )
Description
This locks the specified occurrence and executes the specified function for that occurrence.
Arguments
occurrence
The occurrence number.
function_name
The name of the function that must be executed. The function must be of type void.
...
Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Functions reference
19-13
Form and form field operations
Context
4Gl library function.
You can use this function only in 4GL scripts, of types 2 and 3. You can use it in the following event subsections: before.choice, on.choice, after.choice
before.input, on.input, after.input, check.input
when.field.changes
before.zoom, after.zoom
See also
do.all.occ(), do.occ.without.update(), on.old.occ()
Syntax
do.occ.without.update( long occurrence, function_name
[, ...] )
Description
This executes the specified function for a specified occurrence, without any locking or update actions.
Arguments
occurrence
The occurrence number.
function_name
The name of the function that must be executed. The function must be of type void.
...
Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Functions reference
19-14
Form and form field operations
Context
4Gl library function.
You can use this function only in 4GL scripts, of types 2 and 3. You can use it in the following event subsections: before.choice, on.choice, after.choice
before.input, on.input, after.input, check.input
when.field.changes
before.zoom, after.zoom
See also
do.all.occ()
, do.occ()
, on.old.occ()
Syntax
void enable.commands( string command [, string command]...)
Description
This enables the specified standard and/or form command(s). Standard commands are identified by their command IDs. Form commands are identified either by a function name, a session code, or a menu code.
Notes
The standard program can enable and disable form commands depending on the number of occurrences currently selected in the form.
You cannot use enable.commands() to enable commands that have been disabled either in the form definition or because the user is not authorized for the commands.
Context
4GL library function.
Example
enable.commands( "test.function", "ttadv3500m000", ADD.SET )
Functions reference
19-15
Form and form field operations
Syntax
void enable.fields( string field [, string field]... )
Description
This enables the specified single-occurrence and/or multioccurrence field(s) on a form.
The field argument identifies the field to be enabled. For a single-occurrence field, this is the field name. For a multioccurrence field, this can be either the field name or the field name followed by an occurrence number (depending on whether you wish to enable all occurrences of the field or only one particular occurrence).
For array fields, UTC fields, and segmented fields, you can append suffixes to the field name to indicate the particular element or segment to be enabled. If you omit these suffixes, all elements/segments are enabled.
n
To enable a particular element of an array field, append the element number
(in parentheses) to the field name. The element number must be an integer, formatted as a string. It cannot be a variable. For example:
"tfmod100.perd(10)"
.
n
To enable only the date or time element of a UTC field, append either .date or
.time to the field name. For example:
"ttadv300.cdat.time"
.
n
To enable a particular segment of a segmented field, append
.segment.segment_id to the field name. For example:
"tiitm001.item.segment.1"
.
Context
4GL library function.
You can use this function in the following 4GL event subsections:
if you want to enable fields after the data has been read from the database but before the fields are displayed on the form. Include it in the when.field.changes section if you want to enable certain fields whenever the content of a related field changes.
Functions reference
19-16
Form and form field operations
Examples
| Enable two named single-occurrence fields enable.fields( "tccom010.beca", "tccom010.dsca" )
| Enable element number 10 of an array field enable.fields( "tfmod100.perd(10)" )
| Enable elements 1 to 12 of an array field for i = start to 12 enable.fields( "month(" & str$(i) & ")" ) endfor
| Enable the date element of a UTC field ttaad500.fidt = 0 enable.fields( "ttaad500.fidt.date" )
| Enable the first and second segments of a segmented field enable.fields( "tcibd001.dfit.segment.1",
"tcibd001.dfit.segment.2" )
Syntax
void execute( long command )
Description
This executes the specified standard command. Normally, standard commands are activated by the user. This function enables applications to execute standard commands without user intervention. This is useful, for example, if you want to display the first record of the main table when a session is started.
Infinite recursion is possible when using this command. For example, if you include execute(add.set) in the after.choice subsection of choice.add.set.
So, never use this function to execute a standard command in its own choice sections.
Note
For a list of all standard commands and the program types in which you can use them, see “Standard commands” in Chapter 3 in U7168A US BaanERP Tools:
Programming Features.
Functions reference
19-17
Form and form field operations
Context
4GL library function.
You can use this function in 4GL scripts only. You can use it in the following event subsections: before.choice, on.choice, after.choice
init.form, before.form, after.form, on.entry
You cannot use the function in the after.choice section of choice.update.db.
Example
form.2: init.form: execute( first.set )
Syntax
long get.field.label( const string fname, long element, ref string label1 mb, ref string label2 mb, ref string label3 mb )
Description
This retrieves the label text associated with the specified field. The function is relevant to dynamic forms only.
fname element
The field name.
For an array field, use this to specify the array element for which you wish to retrieve the label.
label1 to label3 A field can have up to three labels. These return the text of the first, second, and third labels respectively (if they exist).
Return values
>0
-1
-2 number of lines in the label (1, 2, or 3) session is not dynamic field not found
Functions reference
19-18
Form and form field operations
Context
4GL library function.
Example
group.1: before.group: form.hcur = attr.currency$ lines = get.field.label("tfacp200.amth", 1, label1, label2, label3 ) newlabel = label1 & " [" &form.hcur & "]" change.field.label("tfacp200.amth", 1, newlabel )
Syntax
void get.screen.defaults()
Description
The save.defaults standard command enables users to save the current field values of a session as the default values for that session. The
forms of the current session. It is often used at the start of update or print programs, where the user must specify some parameters before executing the session.
If no user defaults are defined, set.fields.default() is executed automatically.
Context
4GL library function.
You can use this function only in form sections of 4GL scripts.
Example
form.1: init.form: get.screen.defaults()
Functions reference
19-19
Form and form field operations
Syntax
void group.invisible( long group.nr )
Description
This hides the specified group completely, including all associated fields, labels, and subgroups. The group.nr argument specifies the group number, as defined in the form editor.
This function is relevant to dynamic forms only.
Context
4GL library function.
You can use this function only in the before.program section of 4GL scripts.
Example
before.program: group.invisible(3)
Syntax
void input.again()
Description
After input by a user, this forces the user to input the data again. If there is an input error, it is preferable to use set.input.error() in the check.input subsection for the field.
Context
4GL library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections: on.input, after.input, when.field.changes, after.field, before.checks
before.zoom
Functions reference
19-20
Form and form field operations
Example
field.pctst999.item: on.input: if pctst999.item(1;1) = "p" then print_item() input.again() endif
Syntax
void inputfield.invisible( string field_name(18) [, string field_name(18)]... )
Description
This hides the specified field(s) completely. In dynamic sessions, associated labels and dependent child fields are also hidden. To hide a particular element of an array field, append the element number (in parentheses) to the field name. For example:
"ttadv301.labl(2)"
.
Note that when the predefined variable attr.echo is set to off, the field value is not displayed but the field itself remains visible.
Note
Use inputfield.visible() to redisplay the field again. Use is.field.invisible() to check whether a specified field is currently visible or invisible.
Context
4GL library function.
You can use this function only in 4GL scripts. For dynamic forms, you can use this function only in the before.program section.
Example
before.field: inputfield.invisible( "ttadv200.cpac", "ttadv200.crel" )
Functions reference
19-21
Form and form field operations
Syntax
void inputfield.password( string field_name(18) [, string field_name(18)]... )
Description
This causes input to the specified field to be displayed as asterisks (*). To specify a particular element of an array field, append the element number (in parentheses) to the field name. For example:
"ttadv301.labl(2)"
.
Context
4GL library function.
You can use this function only in 4GL scripts. For dynamic forms, you can use this function only in the before.program section.
Syntax
void inputfield.visible( string field_name(18) [, string field_name(18)]... )
Description
Use this to redisplay one or more fields made invisible by inputfield.invisible().
To redisplay a particular element of an array field, append the element number
(in parentheses) to the field name. For example:
"ttadv301.labl(2)"
.
Note
Use is.field.invisible() to check whether a specified field is currently visible or invisible.
Context
4GL library function.
You can use this function only in 4GL scripts. For dynamic forms, you can use this function only in the before.program section.
Functions reference
19-22
Form and form field operations
Example
before.field: inputfield.visible( "ttadv200.cpac" )
Syntax
long is.field.invisible( string field_name(18) )
Description
This checks whether a specified field is currently visible or invisible. To specify a particular element of an array field, append the element number (in parentheses) to the field name. For example:
"ttadv301.labl(2)"
.
Note
Use inputfield.invisible() to hide a field. Use inputfield.visible() to redisplay it again. For dynamic forms, you can use this function only in the before.program section.
Return values
FALSE field is visible
TRUE field is invisible
Context
4GL library function.
You can use this function only in 4GL scripts.
Example
if not is.field.invisible( "ttadv200.cpac" ) then display( "ttadv200.cpac" ) endif
Functions reference
19-23
Form and form field operations
Syntax
void make.current()
Description
This reads the current main table record and displays it on screen. Calling this function is similar to calling execute(find.data)
, except that if the specified record is not present, make.current() does not read the next record.
Context
4GL library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections: before.choice, on.choice, after.choice
init.form, before.form, after.form
Syntax
void mark.occ( long occurrence )
Description
This marks the specified occurrence with a reverse bar, makes the marked record the current record in the database, and sets the predefined variable actual.occ to the marked occurrence.
The following predefined variables are relevant to this function: marked Use this to check whether an occurrence is marked or not.
This can also be tested in the on.exit subsection of a zoom process.
Functions reference
19-24
Form and form field operations
mark.status
This is available in the subsections before.choice and
marking that the standard program is executing. It can have the following values:
DUPL.OCCUR
TEXT.MANAGER
0 during marking for copying during marking for edit text in all other cases and when not marking
Note
Use remove.mark() to unmark the occurrence.
Context
4GL library function.
You can use this function only in 4GL scripts, and only in choice and form sections of those scripts. You cannot use it in programs of type 4.
Syntax
void on.old.occ( function_name [, ...] )
Description
This executes the specified function for the current occurrence, using the old values of the record. The record must have been previously modified.
Arguments
function_name
The name of the function that must be executed. The function must be of type void.
...
Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Note
In DAL scripts, with.old.object.values.do() is the equivalent of on.old.occ().
Functions reference
19-25
Form and form field operations
Context
4Gl library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections: before.rewrite, after.rewrite
before.write, after.write (in the case of dupl.occur or global.copy)
See also
do.all.occ(), do.occ(), do.occ.without.update()
Example
declaration: long old_inventory choice.cont.process: on.choice: do.all.occ( update_occurrences, 9999 ) main.table.io: before.rewrite: on.old.occ( get_old_inventory ) pctst999.change = pctst999.item - old_inventory functions: function void update_occurrences( long new_val )
{ pctst999.special = new_val
}
Syntax
void print.const( [string fill_string(127)] )
Description
This displays a specified constant string value in the current form field. The current value of the database field is not affected.
If you do not include the fill_string argument, the field is filled with asterisk characters (*). If the argument is a string of length one, the field is filled with the
Functions reference
19-26
Form and form field operations
specified character. If the argument is a string of length greater than one, the specified string is displayed in the field, without repetition. The maximum length for the string is 127 characters.
Context
Bshell function.
You can use this function only in 4GL scripts. As it operates on the current field, you can use it only in field sections.
Example
field.pctst999.desc: after.display: if pctst999.number = 0 then print.const("?") | Display "????????" in the
| current field endif if pctst999.number = 99999 then print.const(" ") | Blank the current field endif
Syntax
void refresh.curr.occ()
Description
This reads the current record and refreshes it on screen. All references on the form are read again. For example, in the case of a zoom from a field to a session where the record can be modified, calling refresh.curr.occ() refreshes the occurrence on the parent form also.
Note that the function locks the record before reading it; this is necessary for delayed locks.
Context
4GL library function.
You can use this function only in 4GL scripts. You cannot use it in programs of type 4.
Functions reference
19-27
Form and form field operations
Syntax
void remove.mark()
Description
This unmarks an occurrence previously marked by using mark.occ(). Do not use this function to remove marks set by the standard program.
Context
4GL library function.
You can use this function only in 4GL scripts, and only in choice and form sections of those scripts. You cannot use it in programs of type 4.
Syntax
void set.fields.default()
Description
It is possible to define default values for form fields with the form editor. For all fields of the current form, this function sets the corresponding script variables to the default form values.
The function is often used before batch or print programs, where the user must specify some parameters for the batch run.
Context
4GL library function.
You can use this function only in form sections of 4GL scripts.
See also
get.screen.defaults()
Functions reference
19-28
Form and form field operations
Example
form.1: init.form: set.fields.default()
Syntax
void stp.reset.value()
Description
This resets the value in the current field to its previous value. You can use this function only after input to the field.
Context
4GL library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections: on.input, after.input, check.input
In a check.input subsection, you cannot use this function before a save operation. To ensure this, program the section as follows: check.input: if not before.update.check then endif stp.reset.value()
Syntax
void to.field( field )
Description
This transfers control of the standard program to the specified field after input to or display of the current field. This overrides the TAB sequence of the form. You can specify the field by using the field number or a string containing the field name.
Functions reference
19-29
Form and form field operations
After handling the specified field, control passes to the next field in the TAB sequence.
Note
In a well-designed GUI, users (and not the application) select and initiate the actions to be performed. Using to.field() removes control from the user.
Therefore it does not conform to good GUI design principles.
Context
4GL library function.
You can use this function only in 4GL scripts. You can use it in the following event subsections: after.input, after.display, after.field
See also
to.form()
Syntax
void to.form( long form_number )
Description
This forces a switch from the current form to the specified form. The
form_number argument must specify an existing form in the session, and must be in the range one to the value of the predefined variable number.forms. During the switch operation, the after.form subsection of the current form is executed and the init.form and before.form subsections of the new form are executed.
The init.form subsection is executed only the first time a form becomes current.
The following predefined variables are relevant to this function: number.forms
indicates the total number of forms in the session form.prev
form.curr
form.next
indicates the previous form number indicates the current form number indicates the next form number
Functions reference
19-30
Form and form field operations
Note
In a well-designed GUI, users (and not the application) select and initiate the actions to be performed. Using to.form() removes control from the user.
Therefore it does not conform to good GUI design principles.
This function is not relevant for dynamic forms.
Context
4GL library function.
You can use this function only in 4GL scripts, and only in choice and form sections of those scripts.
Example
| Suppose there is a special form (form 4) for a form command
| When the user chooses this command, form 4 is started declaration: long old_curr_form function extern my.form.command()
{ old_curr_form = form.curr
to.form( 4 )
. . . | perform some action(s) to.form( old_curr_form )
}
Syntax
long to.group( long group.nr )
Description
Use this to make the first form on which the specified group occurs the current form. This function is relevant to dynamic forms only.
In a well-designed GUI, users (and not the application) select and initiate the actions to be performed. Using to.group() removes control from the user.
Therefore it does not conform to good GUI design principles.
Functions reference
19-31
Form and form field operations
Return values
1
0 success group not found
Context
4GL library function.
Syntax
void update.occ()
Description
The standard program automatically detects changes a user makes to a field.
However, it cannot detect changes to field values made in the program script.
When you modify a field of the main table in the program script, you must call
ensures when that the database is next updated, the modifications are saved to the database. The database update action can be initiated either by the user or within the script (use execute(update.db)
).
Before the update.db command is executed, the user can undo the changes with the recover.set command. If you do not want users to be able to undo changes, you can force an immediate update by calling execute(update.db)
in the script.
Context
4GL library function.
You can use this function only in 4GL scripts, and only in choice and field sections of those scripts.
Functions reference
19-32
Form and form field operations
Example
choice.cont.process: on.choice: do.all.occ(update.occurrences) functions: function void update.occurrences()
{ tiitm001.special = 9999 update.occ() | Sets flag to indicate change
}
See also
do.occ()
Functions reference
19-33
Form and form field operations
Functions reference
19-34
Use these functions for formatting input and output strings.
string edit$ string sprintf$ long string.scan
string vsprintf$
( expression, string format(.) )
( string format(.) [, expression,...])
( str_expr, string format(.) [, variable, ...] )
( string format(.) [, ...] )
Syntax
string edit$( expression, string format(.) )
Description
This formats an expression according to a specified format.
Arguments
expression
The expression that must be formatted. This can be a floating point expression, an integer expression, or a string expression that returns an integer or a floating point value.
Functions reference
20-1
Formatting input and output
format
A string that defines the required format. The following formatting characters are available:
9 Use to reserve a position for a digit. Inserts a 0 if there is no significant digit in that position.
Z Use to reserve a position for a digit. Inserts a space if there is no significant digit in that position. You can use this both before and after the decimal sign.
V Use to indicate the position of the decimal sign. No decimal sign is displayed. To display a decimal sign, you must enter
‘D’, a period [.], or a comma [,] immediately after this character, depending on which decimal sign you wish to use.
D Use to display the decimal sign as defined in the data dictionary.
T Displays a thousand sign. The representation of the thousand sign is defined in the data dictionary.
If this is the first or last character in a format string, a negative value is prefixed or suffixed by a minus sign [-] and a positive value is prefixed or suffixed by a space.
Minus signs in other positions have the same meaning as
‘Z’.
+
*
If this is the first or last character in a format string, a negative value is prefixed or suffixed by a minus sign [-] and a positive value is prefixed or suffixed by a plus sign
[+]. Plus signs in other positions have the same meaning as
‘Z’.
If this is the first character in a format string, all spaces to the left of the most significant digit are filled with asterisks
[*].
All characters other than those described above are copied directly to the output string. Periods [.] and commas [,] are exceptions. These are reserved for use as decimal signs and thousand signs.
If the format expression is enclosed by parentheses, these are displayed only if the result is negative.
Functions reference
20-2
Formatting input and output
Return values
The function returns the formatted expression. If the specified expression does not fit in the format string, the result is filled with the overflow characters defined in the data dictionary.
Note
To include currency symbols or to use formats defined in the data dictionary, use
Context
Bshell function.
Examples
These examples assume that the decimal sign, thousand sign, and overflow character are defined in the data dictionary as a period [.], comma [,] and hash sign [#] respectively
5286.45
463.897
34.65
-3.1
5286.45
463.897
34.65
-3.1
5286.45
463.897
34.65
-3.1
5286.45
463.897
34.65
-3.1
34.65
-3.1
9999VD99
9999VD99
9999VD99
9999VD99
ZZZZVD99
ZZZZVD99
ZZZZVD99
ZZZZVD99
----VD99
----VD99
----VD99
----VD99
++++VD99
++++VD99
++++VD99
++++VD99
+ZZZVD99
+ZZZVD99
5286.45
0463.89
0034.65
#######
5286.45
463.89
34.65
-3.10
5286.45
463.89
34.65
-3.10
5286.45
+463.89
+34.65
-3.10
+34.65
-3.10
overflow no space for no space for +
Functions reference
20-3
Formatting input and output
5286.45
-3.1
5286.45
-3.1
5286.45
463.897
34.65
ZZZZVD99-
ZZZZVD99-
ZZZZVD99+
ZZZZVD99+
*ZZZVD99
*ZZZVD99
*ZZZVD99
5286.45
3.10-
5286.45+
3.10-
######
463.89
*34.65
-3.1
5286.45
463.897
5286.45
*ZZZVD99
ZTZZZVD99
ZTZZZVD99
ZDZZZVD99
*-3.10
5,286.45
463.89
5.286.45
463.8970
ZZZVD99ZZ 463.897
-3.1
(ZZZVD99) (3.10)
3.1
(ZZZVD99) 3.10
overflow
Syntax
string sprintf$( string format(.) [, expression, ...] )
Description
This formats a string and returns the formatted string. The format argument contains zero or more ordinary characters and substitution symbols. The ordinary characters are copied directly to the output string. The substitution symbols specify formats for the values specified in the expression arguments and are substituted by these formatted values.
The substitution symbols are used in the sequence in which they are specified.
The first substitution symbol is used for the first expression argument. The second substitution symbol is used for the second expression argument, and so on.
In addition to a range of numeric type expressions, the function supports dates, amounts, single-byte strings, multibyte strings, bidirectional strings, and combined normal and bidirectional strings. input strings that contain bidirectional strings must be specified in logic order. The result is also returned in logic order.
Functions reference
20-4
Formatting input and output
Substitution symbols
Substitution strings have the following syntax:
%[-][ min][.max]type
The elements of a substitution string have the following meanings:
%
-
All substitution strings begin with a percentage character [%]. To output the percentage character itself, specify it as ‘%%’.
An optional flag indicating that the output string is to be left justified.
If this is omitted, the output string is right justified by default.
min Specifies the minimum length of the output field. If the output string has fewer characters than the minimum field width, it is filled out with spaces. By default, these are inserted at the start of the field. If the ‘-‘ flag is specified, the spaces are inserted at the end of the string.
Instead of an integer constant, you can specify the length with an asterisk [*]. In this case, the corresponding expression argument must supply the length.
max Specifies either the maximum number of digits after the decimal sign
(for ‘%e’ and ‘%f’ substitution types), the maximum number of digits
(for ‘%g’ substitution types), or the maximum string length (for ‘%s’,
‘%A’, ‘%D’, ‘%u’, and ‘%U’ substitution types).
Instead of an integer constant, you can specify the length with an asterisk [*]. In this case, the corresponding expression argument must supply the length.
type The type of conversion to be applied to the substituted value (see below).
Functions reference
20-5
Formatting input and output
The type element can have one of the following values:
%Axxx[,CUR] Use for amounts.
xxx is the code for an amount format defined in the data dictionary. CUR indicates the currency code to use. It this is omitted, the default currency of the company of the user is used.
%Dxxx[,lang] Use for dates.
xxx is the code for a date format defined in the data dictionary. lang indicates the language code to use. If this is omitted, the current user language is used.
The expression that is substituted for this symbol must specify a number of days since 01-01-0001.
%D(format) Use for dates.
This option enables you to define your own date format by using the following subformats of the ‘%D’ format:
%m month in year
%w week in year
%W
%d
%e
%j
%y
%Y week in year day in month day in week day in year year without century year with century
%h name of month
(abbreviated)
%H name of month
%a name of day
1 - 12
0 - 53 week 0 in previous year week 53 in current year
1 - 53 week 53 in previous year
1 - 31
1 - 7
1 - 365
01 - 99
1 - 9999
(‘Jan’ - ‘Dec’)
(‘January’ - ‘December’)
(‘Sun’ - ‘Sat’)
(abbreviated)
%A name of day
(‘Sunday’ - ‘Saturday’)
You can combine these subformats with other formats. Note that strings
Functions reference
20-6
Formatting input and output
%uxxx
%Uxxx
%u(format)
%U(format)
%d
%e
%f
%g
%s
%o
%x
%@format@ returned by name of month and day formats are language dependent.
Use for UTC dates. xxx is the code for a UTC date format defined in the data dictionary.
Use for UTC times. xxx is the code for a UTC time format defined in the data dictionary.
Use for UTC dates.
This option enables you to define your own date format by using the subformats described for the ‘%D(format)’ symbol. You can combine these subformats with other formats.
Note that strings returned by name of month and day formats are language dependent.
Use for UTC times.
This option enables you to define your own time using the following subformats of the ‘%U’ format.
%H hours in 24 hour format
%L hours in 12 hour format
%m minutes
%s seconds
%a substitutes the am/pm symbol as defined for the user
%x time separator as specified for the user language
You can combine these subformats with other formats.
Use for long values.
Use for double values with exponent.
Use for doubles values with 6 decimal places.
Use for double values.
Use for single-byte and multibyte strings.
Use for octal representations of numbers.
Use for hexadecimal representations of numbers.
Use for formatting values by using the formatting characters described for edit$().
Functions reference
20-7
Formatting input and output
Return values
The formatted string. If you specify an invalid format, sprintf$() returns a percentage character [%].
Context
Bshell function.
Examples
Format
%f
%10f
%10.2f
%-10.2f
%10.6g
%10.2e
%-10.2e
%10d
%10d
%-10d
%-10d
%10s
%-10s
%10s
%.10s
%@ZZVD99@
%s
%20s
%-20s
%20.20s
Value
1.2
1.2
1.2
1.267
1234.567
12.34
12.34
1
-1
1
-1
"12"
"12"
"123456789012"
"123456789012"
1.267
Result
"1.200000"
" 1.200000"
" 1.20"
"1.27 "
" 1234.57"
" 1.23e+01"
"1.23e+01 "
" 1"
" -1"
"1 "
"-1 "
" 12"
"12 "
"123456789012"
"1234567890"
" 1.26"
Returns the full string.
Right justifies the string in a field of 20 positions. If the string is longer 20 positions, the field is lengthened to accommodate the full string.
Left justifies the string in a field of 20 positions. If the string is longer 20 positions, the field is lengthened to accommodate the full string.
Right justifies the string and limits its size to 20 positions.
Partially displayable multibyte characters (2 characters wide) will be spaced out.
Functions reference
20-8
Formatting input and output
Strings
string result(80), word(20) word = "word" result = sprintf$("This is a ’%*s’ of 10 positions",10,word)
| result contains "This is a ’ word’ of 10 positions"
Doubles
string result(80) result = sprintf$("number: %-*.*f",10,2,1.2")
| result contains "number: 1.20 "
| minimum length of the double value is 10 positions
| number of digits after decimal sign is 2
Amounts
| Suppose the default currency is USD ($)
| and A001 is defined as "$$ 999T999T999VD99" string result(80) result = sprintf$("%A001", 1234.56)
| result contains "$ 000,001,234.56" result = sprintf$("%-10A001,hfl", 1234.56)
| result contains "fl 000.001.234,56" result = sprintf$("%-.10A001,hfl", 1234.56)
| result contains "001.234,56"; there is insufficient
| space for currency symbol
Dates
| Suppose date format 002 is: "year/month/day in month" string result(80) result = sprintf$("%D002", 727168)
| result contains "1991/12/2"
| Example of substitution symbol %D(format) string result(80) result = sprintf$("%D(Date: %02d/%02m/%04Y)", date.num())
| result contains "Date: 12/07/1993" result = sprintf$("Date: %D(%02d %-20H %04Y)", date.num())
| result contains "Date: 12 June 1993"
Functions reference
20-9
Formatting input and output
UTC dates and times
| Date format 002 is "year/month/day in month"
| Time format 001 is "12 hour format:minutes:seconds
| AM/PM symbol" string result(80) result = springf$("%u002 %001", utc.num(), utc.num())
| Result contains "1997/01/01 10:02:53 pm" string result(80) result = sprintf$("UTC: %u(%02d/%02m/%04Y)
%U(%02h%x%02m%x%025 %a)", utc.num(), utc.num())
| result contains "UTC: 22/07/1997 06:24:53 am"
| provided that for the user’s language the time
| separator is ":" and the AM symbol is "am"
Syntax
long string.scan( str_expr, string format(.) [, variable,
...] )
Description
This scans an input string (str_expr) for one or more fields and stores each individual field found in the first available variable argument. The format argument contains conversion symbols that the function uses to interpret the input string and retrieve the individual field values. The conversion symbols indicate the types of values expected:
%s expects a single-byte or multibyte string
%f expects a double
%d expects a long
An input field is defined as all characters up to the next separator character or up to the next character that does not match the type of the corresponding conversion symbol.
A separator character is a single character used to separate individual values in the input string. It can be a space character, or any other character that is not used within individual fields in the input string. You cannot use multibyte characters as separators.
Functions reference
20-10
Formatting input and output
The string.scan() function scans the input string using each conversion symbol in the format argument in turn. For each conversion symbol, it scans the input string for characters that match the specified format. It stops scanning when it meets a separator character or a character that does match the expected type.
For example, consider the following function call: string.scan( input_string, "%d|%f",long,double )
In this case, the function expects input_string to contain two separate numeric values. It reads the input string until it meets a pipe [|] character (this is the separator specified in the format argument). It then converts the characters read
(excluding the separator) to a long value and stores that value in the long variable. The function then continues scanning the input string using the next conversion symbol in the format argument.
Note that if two conversion symbols are separated by more than one separator character, the function ignores those characters unless they match the input.
Return values
The function returns the number of scanned fields.
Context
Bshell function.
Example
double D long L string S(80) long ret ret = string.scan("string 123 456.78","%s %d %f",S,L,D)
| S contains "string", L contains 123, D contains 456.78
ret = string.scan("string|123|456.78","%s|%d|%f",S,L,D)
| S contains "string", L contains 123, D contains 456.78
Functions reference
20-11
Formatting input and output
Syntax
string vsprintf$( string format(.) [, ...] )
Description
This acts the same as sprintf$(), except that the arguments to be substituted for the substitution symbols in the format argument are not known until run time.
Context
Bshell function.
Example
extern string my.message(256) mb function void create.my.message ( string X(14), ... )
{ my.message = vsprintf$( form.text$(X), ... )
}
Functions reference
20-12
In the BAAN 3GL programming language, you can define a function with a varying number of arguments. For example: function long change.attributes( long id, ... )
{
......
}
The ellipses [...] in the function definition indicates that the number of function arguments is variable, up to a maximum of 255. The function call determines how many and which arguments the function uses.
The functions described in this section enable programs to check how many arguments a function uses, to retrieve their types and values, and to assign values to them.
The arguments cannot be arrays.
long long get.argc
get.arg.type
double get.double.arg
long get.long.arg
string get.string.arg
long put.double.arg
long long put.long.arg
put.string.arg
( )
( long arg_no )
( long arg_no )
( long arg_no )
( long arg_no )
( long arg_no, double value )
( long arg_no, long value )
( long arg_no, string value )
Functions reference
21-1
Functions with varying numbers of arguments
Syntax
long get.argc()
Description
This returns the number of arguments that the function in which get.argc() is implemented contains. Once you know this number, you can read and write to particular arguments using the other functions.
Context
Bshell function.
Syntax
long get.arg.type( long arg_no )
Description
This returns the type of the specified argument.
Arguments
arg_no
The sequence number of an argument of the function in which
Return values
The function can return any of the following values:
DB.LONG
DB.STRING
DB.DOUBLE
DB.MULTIBYTE
Context
Bshell function.
Functions reference
21-2
Functions with varying numbers of arguments
Syntax
double get.double.arg( long arg_no ) long get.long.arg( long arg_no ) string get.string.arg( long arg_no )
Description
These return the value of a specified argument. For get.double.arg(), the argument must be of type double. For get.long.arg(), the argument must be of type long. For get.string.arg(), the argument must be of type string or multibyte string.
Arguments
arg_no
The sequence number of an argument of the function in which
Return values
The value of the specified argument.
Context
Bshell functions.
Syntax
long put.double.arg( long arg_no, double value ) long put.long.arg( long arg_no, long value ) long put.string.arg( long arg_no, string value )
Description
These assign a value to a specified argument. For put.double.arg(), the argument must be of type double. For put.long.arg(), the argument must be of type long. For put.string.arg(), the argument must be of type string or multibyte string.
Functions reference
21-3
Functions with varying numbers of arguments
Arguments
arg_no
The sequence number of an argument of the function in which
value
The value to assign to the argument.
Return values
0
-1 success error; probably invalid argument number
Context
Bshell functions.
function long change.attributes( long id, ...)
{ long i, long_value double double_value for i = 2 to get.argc() on case get.arg.type(i) case DB.LONG: long_value = get.long.arg(i)
......
break case DB.DOUBLE: double_value = get.double.arg(i)
......
break default:
......
break endcase endfor
} function call: change.attributes( window_id, DS_BACKGROUND, CW.GREEN,
DS_FOREGROUND, CW.WHITE, DS_WIDTH, 80, DS_HEIGHT, 40
)
Functions reference
21-4
Use these functions to handle communication between different BAAN processes running in the same bshell.
The BMS mechanism supports broadcast messages, enabling messages to be sent to multiple processes. Messages can be up to 2048 characters long.
The sender process can use process IDs or masks to determine which processes a message is sent to.
n
Masks: A mask is a character string used to control which messages a process can receive. It can be added to any process by using the bms.add.mask() function. If the sender of a message specifies a mask for that message, the message is sent only to those processes to which the specified mask has been added.
n
Process IDs: Instead of, or in addition to a mask, the sender of a message can specify the process ID of the process for which the message is intended. The message is then sent only to that process. If a mask is also specified for the message, the process can receive the message only if the mask was previously added to the process.
Receiving processes can use masks and levels to control which messages it receives.
n
Masks: If a particular mask is added to a process, the process can receive all messages sent with that mask.
n
Levels: The sender of a message can specify a level for that message.
Receiving processes can then choose which level of messages they wish to receive.
There are four predefined broadcast messages that the system can send to processes. Processes must set the bms.shutdown, bms.exit, bms.exit.child, bms.startup, and bms.startup.child masks to receive these messages.
Functions reference
22-1
Interprocess communication (bshell)
n
bms.shutdown: When this mask is set for a process, the message bms.shutdown is sent to the process when all processes that do not have this mask set have ended. It indicates that the process must exit because the bshell wants to stop.
n
bms.exit: When this mask is set for a process, the exit value of an ended process is sent to the process. The received message contains the string exit<exit.value>. The process number of the exited process is provided in evt.bms.sender(event).
n
bms.exit.child: When this mask is set for a process, the exit value of an ended child process is sent to the process. The received message contains the string exit.child<exit.value>.
n
bms.startup: When this mask is set for a process, the message startup is sent to the process when a process is started.
n
bms.startup.child: When this mask is set for a process, the message startup.child is sent to the process when a child process is started.
Note that when one of the above message is sent, evt.bms.command(event) is zero.
Bucket messages provide a simple mechanism for two processes to exchange small packets of information (up to 100 characters long). A process uses
process calls receive.bucket$() to receive the next bucket message sent to it by any other process.
See also
Chapter 24, Interprocess communication (operating-system level)
Functions reference
22-2
Interprocess communication (bshell)
void void string long long bms.add.mask
bms.delete.mask
( string mask(32) [, long processno] )
( string mask(32) [, long processno] ) bms.receive$ ( [ref long level, long wait.flag, ref string mask()]) bms.receive.buffer
( ref string broadcast(), ref long no.bytes [, long level, long wait.flag, ref string mask()] ) bms.send
( string broadcast(2048), long level_or_evt[(EVTMAXSIZE)], string mask(32), long processno [, long no.bytes] )
string receive.bucket$ long send.bucket
long send.wait
( ref long processno )
( long processno, string bucket(100) )
( long processno, string bucket(100) )
Syntax
void bms.add.mask( string mask(32), [, long processno] )
Description
This adds the specified mask to a process. If you specify a process number, the mask is added to that process. Otherwise, the mask is added to the current process.
Context
Bshell function.
Functions reference
22-3
Interprocess communication (bshell)
Syntax
void bms.delete.mask( string mask(32), [, long processno] )
Description
This removes the specified mask from a process. If you specify a process number, the mask is removed from that process. Otherwise, the mask is removed from the current process.
Context
Bshell function.
Syntax
string bms.receive$( [ ref long level, long wait.flag, ref string mask()] )
Description
Use this to receive a broadcast message. If no arguments are included, the function returns the first broadcast message sent to the process.
Arguments
level
This optional argument specifies a message level. The following values are available:
0
>0
<0 the function returns the first broadcast message sent to the process the function returns the first broadcast message sent with the specified level the function returns the first broadcast message sent with a level less than or equal to the absolute value of the specified level
This argument returns the process ID of the sending process. The process ID overwrites the specified level.
Functions reference
22-4
Interprocess communication (bshell)
wait.flag
This optional argument indicates whether the process must wait for a broadcast message if no message has yet been sent:
0 wait
<>0 do not wait
If you include this argument, you must also include the level argument.
mask
This optional argument returns the mask (if any) sent with the message.
Return values
The received broadcast message.
Context
Bshell function.
Syntax
long bms.receive.buffer( ref string broadcast(), ref long no.bytes [, long level, long wait.flag, ref string mask()] )
Description
Use this to receive a broadcast message. The function can retrieve a complete record, including ‘\0’ characters.
Arguments
broadcast
This returns the received broadcast message.
no.bytes
This returns the number of bytes in the broadcast message.
Functions reference
22-5
Interprocess communication (bshell)
level wait.flag
mask
This optional argument specifies a message level. The following values are available:
0 the function returns the first broadcast message sent to the
process
>0 the function returns the first broadcast message sent with
the specified level
<0 the function returns the first broadcast message sent with a level less than or equal to the absolute value of the specified level
This optional argument indicates whether the process must wait for a broadcast message if no message has yet been sent:
0 wait
<>0 do not wait
If you include this argument, you must also include the level argument.
This optional argument returns the mask (if any) sent with the message.
Return values
The ID of the sending process.
Context
Bshell function.
Syntax
long bms.send(( string broadcast(2048), long level_or_evt[(EVTMAXSIZE)], string mask(32), long processno [, long no.bytes] )
Description
Use this to send a broadcast message to one or more processes.
Functions reference
22-6
Interprocess communication (bshell)
Arguments
broadcast
The message that must be sent.
level_or_evt
Use this either to specify a level for the message (1 or 2, for example) or to specify an event array with the following information: evt.type( event ) evt.bms.sender( event ) this is always
EVTBUCKETMESSAGE sender ID (this is filled automatically) evt.bms.command( event ) command ID evt.bms.argument( event ) some argument
The specified event is sent to each process to which the broadcast message is sent.
mask processno no.bytes
If you specify a mask in this argument, the message is sent to all processes to which that mask has been added. If you also specify a process ID in the processno argument, the process is sent only to the specified process.
If you specify a process ID in this argument, the broadcast message is sent only to that process. If you specify 0 for this argument, the mask argument is used to indicate the processes to which the message is sent.
The size of the broadcast message, in bytes.
Notes
If bms.send() specifies a mask and no processes have that mask set, the file
‘$BSE/lib/bms_mask’ is searched for a line beginning with the mask name.
Lines in this file have the following syntax:
<mask>:<process>:<y/n>:[boot]
When a line is found that begins with the specified mask, the process specified in that line is started. If the line contains ‘y’, the mask is automatically added to the process. The broadcast message and event are then sent to the process. If the line contains ‘n’, the mask is not added to the process and so the process does not receive the message and event. If the line ends with the word ‘boot’, the specified process is always started automatically before any other process when the bshell starts.
Functions reference
22-7
Interprocess communication (bshell)
For example:
| suppose the file ’$BSE/lib/bms_mask’ contains the following
| line: calculator:ottstpcalc:y long event(EVTMAXSIZE), bms_id bms_id = bms.send( "", event, "calculator", 0 )
Return values
0
>0 error the process ID of the last process to which the broadcast message was sent
Context
Bshell function.
See also
Chapter 17, Events
Syntax
string receive.bucket$( ref long processno )
Description
This waits for a bucket message to be sent to the calling process by another process. It then returns that message. The processno argument returns the process
ID of the sending process.
Context
Bshell function.
Functions reference
22-8
Interprocess communication (bshell)
Syntax
long send.bucket( long processno, string bucket(100) )
Description
This sends a bucket message to a specified process. If the specified process is sleeping, it is automatically started. It can retrieve the message by calling
Arguments
processno
The process ID of the process to which the message must be sent, as returned by functions such as activate() and act.and.sleep().
In subprocesses, the predefined variable parent indicates the process ID of the parent process.
bucket
The message string.
Return values
>0
-1 the process ID of the called process error
Context
Bshell function.
Syntax
long send.wait( long processno, string bucket(100) )
Description
This sends a bucket message to a specified process and waits for a reply. The receiving process must send a reply by using send.bucket() or send.wait(). Note that the waiting process cannot receive any message string contained in the reply.
Functions reference
22-9
Interprocess communication (bshell)
Arguments
processno
The process ID of the process to which the message must be sent, as returned by functions such as activate() and act.and.sleep(). In subprocesses, the predefined variable parent indicates the process
ID of the parent process.
bucket
The message string.
Notes
When a process that is waiting for a reply from one process receives a message from another process, it is wakened automatically and the data sent is lost.
Return values
>0
- 1 the process ID of the process that sends the reply error
Context
Bshell function.
Example
Process 1: long process process = activate("process2") send.bucket(process, "") | This is the reply, data can
| not be received in process 2
Process 2: send.wait(parent, "I am waiting for a reply")
Functions reference
22-10
Interprocess communication (bshell)
Example 1
| process 1 ret = bms.send("do_action_1", 0, "tfgld1201s000", 0)
| background process "tfgld1201s000" bms.add.mask("bms.shutdown") | to detect the shutdown event
| which is sent by the system
....
bucket = bms.receive$() if bucket = "bms.shutdown" then end.process() | contains del.window command else if bucket = "do_action_1" then action_1() endif endif
Example 2
long event(EVTMAXSIZE) string bms.ret(2048) while true ext.event(event) on case evt.type(event) case EVTBUCKETMESSAGE: bms.ret = bms.receive$() handle.bucket.message( bms.ret ) break case EVTKEYPRESS:
....
case EVTBUTTONPRESS:
....
endcase endwhile function handle.bucket.message( const string bms.str() )
{ string key.of.record(100) on case bms.str
case "first": key.of.record = get.first.record() bms.send(key.of.record, event, "", evt.bms.sender(event))
Functions reference
22-11
Interprocess communication (bshell)
} break case "last": key.of.record = get.last.record() bms.send(key.of.record, event, "", evt.bms.sender(event)) break case "next": key.of.record = get.next.record() bms.send(key.of.record, event, "", evt.bms.sender(event)) break case "prev": key.of.record = get.prev.record() bms.send(key.of.record, event, "", evt.bms.sender(event)) break endcase
Functions reference
22-12
The Baan C Socket Interface is an Interprocess Communication (IPC) mechanism that enables cross-platform IPC over TCP/IP sockets. It is available on all platforms where the Baan Runtime Tools are available.
The Baan C Socket Interface supports bidirectional communication between two related or unrelated processes that are running on the same or on different hosts.
One process is the server, the other is the client. A server process can use the socket mechanism to communicate with multiple clients. A client process can use the socket mechanism to communicate with multiple servers. Moreover, a process can be a server for one connection and a client for another.
The functions provided by the socket interface enable client processes to request a connection with a particular server and to create a socket on which to send data to and receive data from the server. They enable servers to accept connection requests from clients, and to create sockets on which to send data to and receive data from clients.
n
The server process calls sock.listen() to create a socket to which clients can send connection requests. The new socket is used only for receiving connection requests.
n
The server process calls sock.accept() to accept a connection request from a client process and to create a connected socket on which it can send data to and receive data from the client. The connection request is sent by the client to the listen socket created by the server with sock.listen().
Functions reference
23-1
Interprocess communication (cross-platform)
n
A client process calls sock.connect() to request a connection with a particular server. The connection request is sent to the listen socket on the server. If the server accepts the request (with sock.accept()), the client creates a connected socket on which it can send data to and receive data from the server.
n
Both client and server processes use sock.send(), followed by sock.flush(), to send data to the other process via a connected socket. They use sock.recv() to read data from a connected socket.
n
When a socket is no longer needed, or if an error has occurred on the socket, the socket owner can close the socket by calling sock.close(). The process that created the socket is normally the socket owner. However, ownership of a socket can be transferred to another process with the sock.inherit() function.
Data is delivered across a socket connection as a string of bytes without message boundaries. Consequently, when a process reads data from a socket, there is no guarantee that the data received belongs to a single message or consists of an entire message. Possible solutions are: n
Including a length field, of fixed size, as the first field of a message. The receiver can then read the message based on the length value specified in the length field.
n
Including a type field, of fixed size, as the first field of a message. The receiver can then read the message based on the message size indicated by the specified message type.
To read binary data that has been stored in a buffer by sock.recv(), you must use the load.*() functions. When sending binary data with sock.send(), you must store the data in the send buffer by using the store.*() functions.
Both sets of functions assume that data is stored in big endian format (that is, highest byte first). If it is stored in little endian format, you must set the endian argument in the load.*() functions to 1. For example: long total.len
string receive.buffer( 200 ) load.long( total.len, receive.buffer, 1 )
When sending data of type float or double over a socket, the store.float(),
Functions reference
23-2
Interprocess communication (cross-platform)
The data is stored in and retrieved from the send and receive buffers in the native format of the calling machine. So, do not rely on these functions to solve platform differences in floating-point storage formats. One possible solution it to convert floating-point numbers to a printable format before sending them over the socket connection.
See also
Chapter 24, Interprocess communication (operating-system level)
Chapter 22, Interprocess communication (bshell)
Synopsis long sock.accept
long long sock.close
sock.connect
long long long long long sock.flush
sock.inherit
sock.listen
sock.recv
sock.send
( long socket )
( long socket [, linger.timeout] )
( string host.name, string service.name, long timeout )
( long socket )
( long socket )
( string service.name )
( long socket, ref string data, long num.bytes )
( long socket, string data, long num.bytes )
Syntax
long sock.accept( long socket )
Description
A server process uses this to accept a connection request received on a socket created by sock.listen(). The function returns a valid connected socket on which the server process can send data to and receive data from the client process.
Arguments
socket
The file descriptor of a listen socket created by sock.listen().
Functions reference
23-3
Interprocess communication (cross-platform)
Notes
If a program calls sock.accept() when there is no connection request pending on the listen socket, the program is put into a sleeping state until a connection request is received. When a request subsequently arrives, the program resumes and sock.accept() returns a connected socket.
If the calling application enables I/O events by calling select.event.input( 0,
EVTIOEVENTMASK ), before calling sock.accept(), the application will receive an event in the following situations: n
When data is available on the connected socket. To retrieve the data, the application can call sock.recv() on the socket specified in the event.
n
When an I/O error occurs on the connected socket. In this case, the application must call sock.close() to close the socket specified in the event.
You use next.event() to retrieve events from the event queue. For details of I/O events, see “I/O events” in Chapter 17.
Return values
>0 success; a descriptor for the connected socket is returned
<=0 error; the predefined variable e contains the error number
Context
Bshell function.
Syntax
long sock.close( long socket [, long linger.timeout] )
Description
This closes a specified socket.
Functions reference
23-4
Interprocess communication (cross-platform)
Arguments
socket
The file descriptor of a socket created by sock.connect(),
linger.timeout
By default, sock.close() waits for five seconds to enable unsent data to be sent. Use this optional argument to specify a different timeout value. Possible values are:
>0 Specifies the number of seconds the functions must wait
for unsent data to be sent. The bshell blocks during this
timeout period.
0 The function returns immediately, and any unsent data is discarded.
-1 The function returns immediately, while unsent data is still being sent.
The linger timeout is ignored when closing a socked returned by sock.listen().
Note
When a program terminates, all open sockets are automatically closed, with the default linger timeout (that is, five seconds).
Return values
0
-1 success error; the predefined variable e contains the error number
Context
Bshell function.
Syntax
long sock.connect( string host.name, string service.name, long timeout )
Functions reference
23-5
Interprocess communication (cross-platform)
Description
A client process uses this to initiate a socket connection with a specified server.
If the server accepts the connection request, the function returns a valid connected socket on which the client process can send data to and receive data from the server process. The function does not return until either there is a valid connection, or the connection request fails, or a specified timeout expires.
Arguments
host.name
service.name
The specifies the name of a service that maps to a port number.
The service name is translated to a port number via a platformspecific lookup mechanism such as the /etc/services file or
Yellow Pages (YP).
If you do not know the service name, you can specify the port number directly. For example: sock.connect( "10.1.2.39", "23", -1)
timeout
The name of the host where the server process is located. The host name is resolved via a platform-specific lookup mechanism such as the /etc/hosts file or the Domain Name
System (DNS). You can specify the host name as a dotteddecimal IP address, but this is not recommended.
This specifies a timeout period (in seconds) after which the connection request is canceled if there is no response from the system specified by host.name.
If you specify a timeout of <=0, sock.connect() waits until it either succeeds or fails. If possible, do not specify timeout periods of less than five seconds. If you do, connection requests can fail due to a slow network.
Note that the bshell blocks while sock.connect() is being executed.
Notes
If the calling application enables I/O events by calling select.event.input( 0,
EVTIOEVENTMASK ), before calling sock.connect(), the application will receive an event in the following situations: n
When data is available on the connected socket. To retrieve the data, the application can call sock.recv() on the socket specified in the event.
Functions reference
23-6
Interprocess communication (cross-platform)
n
When an I/O error occurs on the connected socket. In this case, the application must call sock.close() to close the socket specified in the event.
You use next.event() to retrieve events from the event queue. For details of I/O events, see “I/O events” in Chapter 17.
Return values
>0 success; a descriptor for the connected socket is returned
<=0 error; the predefined variable e contains the error number
Context
Bshell function.
Syntax
long sock.flush( long socket )
Description
You use sock.send() to place data in the send buffer of a connected socket. The data is automatically transferred on the socket when the buffer is full. But you can also call sock.flush() to transfer the data on the socket.
It is important to always check the return value of sock.flush() to verify whether or not the data has been sent successfully.
Arguments
socket
The file descriptor of a socket created by sock.connect() or
Notes
When the transport system has insufficient buffer space to hold the data to be transmitted, sock.flush() blocks the entire bshell until sufficient space is available. So, be careful not to overflow a receiving program by sending excess data.
If sock.flush() fails, the calling program must call sock.close() to close the socket.
Functions reference
23-7
Interprocess communication (cross-platform)
Return values
0
-1 success error; the predefined variable e contains the error number
Context
Bshell function.
Syntax
long sock.inherit( long socket )
Description
A process calls this function in order to take over ownership of a specified socket from another process. The socket is removed from the list of open files for the process that originally owned the socket; it is added to the list of open files for the calling process. The socket is automatically closed when the new owner process terminates.
The use of sock.inherit() is required when a server starts a new process to handle a connection returned by sock.accept(). The new process must call
the server program will close the socket handled by the new process as well.
Arguments
socket
The file descriptor of a socket created by sock.connect() or
Notes
The sock.inherit() function is valid only for sockets created by sock.connect() or sock.accept().
The new process does not inherit event settings from the original process. If required, the calling application must explicitly enable I/O events by calling
application will then receive an event in the following situations:
Functions reference
23-8
Interprocess communication (cross-platform)
n
When data is available on the connected socket. To retrieve the data, the application can call sock.recv() on the socket specified in the event.
n
When an I/O error occurs on the connected socket. In this case, the application must call sock.close() to close the socket specified in the event.
You use next.event() to retrieve events from the event queue. For details of I/O events, see “I/O events” in Chapter 17.
Return values
0
-1 success error; the predefined variable e contains the error number
Context
Bshell function.
Syntax
long sock.listen( string service.name )
Description
A server calls this function to create a listen socket that it can use to receive connection requests from clients. The function binds the new socket to the address specified by INADDR_ANY and the service specified by service.name.
It returns a valid listen socket that sock.accept() can access in order to accept connection requests.
Arguments
service.name
This specifies the name of a service that maps to a port number. The service name is translated to a port number via a platform-specific lookup mechanism such as the /etc/services file or Yellow Pages (YP).
If you do not know the service name, you can specify the port number directly. For example: sock.listen( "23" )
Functions reference
23-9
Interprocess communication (cross-platform)
Notes
If the calling application enables I/O events by calling select.event.input( 0,
EVTIOEVENTMASK ), before calling sock.listen(), the application will receive an event when a connection request is pending on the socket. The application can then call sock.accept() on the socket specified in the event. You use next.event() to retrieve events from the event queue. For details of I/O events, see “I/O events” in Chapter 17.
When the calling application does not want to accept any new connections, it must close the listen socket by calling sock.close().
Return values
>0 success; a descriptor for the listen socket is returned
<=0 error; the predefined variable e contains the error number
Context
Bshell function.
Syntax
long sock.recv( long socket, ref string data, long num.bytes )
Description
Both client and server processes use this function to read data from a specified connected socket. The function returns only when the number of bytes specified by num.bytes has been received.
Arguments
socket
The file descriptor of the local socket, as returned by
This returns a pointer to the buffer where the data is stored.
data num.bytes
This specifies the number of bytes that must be retrieved. This must not exceed the maximum buffer size (currently, this is 4Kb).
Functions reference
23-10
Interprocess communication (cross-platform)
Notes
If an application attempts to read more data than has actually arrived on the socket, the entire bshell blocks until the number of bytes specified has been received. It is the responsibility of the calling program to ensure that it never calls sock.recv() for more data than can be expected.
If an application calls sock.recv() before data is available on the socket, the application is put into a sleeping state until data arrives. When data subsequently arrives, the program resumes and sock.recv() returns the data.
Return values
>0
0
-1 success; the number of bytes retrieved is returned (this is always the same number as specified by num.bytes)
EOF; the other end of the socket has been closed by its owner process error; the predefined variable e contains the error number
When the return value is 0 or -1, the application must close the local socket by calling sock.close().
Context
Bshell function.
Syntax
long sock.send( long socket, string data, long num.bytes )
Description
You use sock.send() to place data in the send buffer of a connected socket. The data is automatically transferred on the socket when the buffer is full. But you can also call sock.flush() to transfer the data on the socket.
Functions reference
23-11
Interprocess communication (cross-platform)
Arguments
socket data
The file descriptor of the local socket, as returned by
This points to the buffer where the data must be stored.
num.bytes
This specifies the number of bytes that must be sent. This must not exceed the maximum buffer size (currently, this is 4Kb).
Notes
When the transport system has insufficient buffer space to hold the data to be transmitted, sock.send() blocks the entire bshell until sufficient space is available. So, be careful not to overflow a receiving program by sending excess data.
Return values
>0
-1 success; the number of bytes sent is returned (this must always be the same number as specified by num.bytes) error; the predefined variable e contains the error number
When the return value is -1, the application must close the local socket by calling
Context
Bshell function.
Functions reference
23-12
These functions enable BAAN processes in different bshells to communicate with each other. On UNIX platforms you can use both the message queue and pipe mechanisms. On Windows NT platforms you can currently use only message queues.
With the *.message functions, BAAN processes in different bshells can communicate with each other by means of message queues (referred to here as mailboxes). A process can create new mailboxes, connect to existing mailboxes, and read from and write to those mailboxes.
Processes use the open.message() function both to create a new mailbox and to connect to an existing mailbox. The arguments of the open.message() function include a project number and the name of a file that is readable by all processes that want to use the mailbox. The project number and some attribute of the specified file are used internally to generate a numeric key that uniquely identifies the mailbox. All processes that want to use the same mailbox must generate the same key, so they must call open.message() with the same project number and file name arguments.
Once a process has connected to a particular mailbox, it can write to it and read from it by using the send.message() and recv.message() functions. When there is no further use for a particular message queue, you must explicitly destroy it by calling close.message().
On UNIX platforms, the mailbox functions can use the UNIX message queue ID instead of the mailbox key to address a particular mailbox. To do this, all functions must specify 1 in the optional fast argument. Using the UNIX message queue ID has both advantages and disadvantages. For example: n
The UNIX system call to convert the mailbox key to a message queue ID
(msgget()) is called only once – that is, during open.message(). It is not called during send.message(), recv.message(), or close.message(). So, the load on the UNIX system is reduced.
Functions reference
24-1
Interprocess communication (OS level)
n
You cannot use a message queue key that was not returned by
n
Some errors, such as a removed message queue, can be difficult to detect.
On UNIX platforms, the bshell can use unnamed pipes to communicate with an external UNIX process started by the same bshell.
void close.message
long open.message
long recv.message
long send.message
( long key [, long fast] )
( long project, string name$, long action [, long fast] )
( long key, long sender.key, long time, ref string message$ [, long fast] )
( long dest.key, long sender.key, string message$ [, long fast] )
long long long long long long pipe.clearerr
pipe.close
pipe.eof
pipe.error
pipe.flush
pipe.gets
long long long long pipe.open
pipe.puts
pipe.read
pipe.write
( long pipe_id )
( long pipe_id )
( long pipe_id )
( long pipe_id )
( long pipe_id )
( ref string line(80), long nr_of_bytes, long pipe_id )
( string pathnm(128), string openmode(2) )
( string line(80), long pipe_id )
( ref string buffer(1024), long nr_of_bytes, long pipe_id )
( string buffer(1024), long nr_of_bytes, long pipe_id)
Functions reference
24-2
Interprocess communication (OS level)
Syntax
void close.message( long key [, long fast] )
Description
This removes the specified mailbox. All messages in the mailbox are also automatically removed.
Arguments
key
The mailbox key, as returned by open.message().
fast
Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Context
Bshell function.
Syntax
long open.message( long project, string name$, long action
[, long fast] )
Description
Use this to create a new mailbox or to connect to an existing mailbox. You must call this function before you can read from or write to the mailbox.
Functions reference
24-3
Interprocess communication (OS level)
Arguments
project
A number in the range 1 to 255 that indicates the project to which the mailbox belongs.
name$
This identifies a particular mailbox within the specified project. The argument must contain the name of a file that can be read by all processes that want to use the mailbox.
The function uses the specified project number and some attribute of the specified file to generate a mailbox key that uniquely identifies the mailbox. The contents of the file are not used or changed by the function.
Note that within a project, the specified file must be clearly associated with a particular mailbox.
action fast
This argument can have one of the following values:
0
1
2
If the mailbox does not already exist, a new one is created.
This is similar to 0, except that instead of using a file name specified in name$, the system creates a unique file name
("$BSE/TMP/PostB<pid>"). When specifying this option, specify name$ as an empty string ("").
If the mailbox does not already exist, a new one is not created.
Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Return values
This returns a unique key for the opened mailbox. It returns -1 if an error occurs
(the predefined variable e contains the error number).
Context
Bshell function.
Functions reference
24-4
Interprocess communication (OS level)
Syntax
long pipe.clearerr( long pipe_id )
Description
This resets the error and end-of-file indicators on the specified pipe.
Arguments
pipe_id
The pipe ID, as returned by pipe.open().
Return values
0
-1 success error; most probably no connected stream on pipe_id
Context
Bshell function.
Syntax
long pipe.close( long pipe_id )
Description
This clears any buffers associated with the specified pipe and closes the file.
Buffers allocated by the standard input/output system are also cleared. Note that
Arguments
pipe_id
The pipe ID, as returned by pipe.open().
Return values
-1 error
-2 child process is not allowed to read/write anymore
>=0 exit value of child process (0 is OK)
Functions reference
24-5
Interprocess communication (OS level)
Context
Bshell function.
Syntax
long pipe.eof( long pipe_id )
Description
This checks the end-of-file indicator on the specified pipe. Note that the end-offile indicator lasts until the pipe is closed, unless you explicitly clear it by calling
Arguments
pipe_id The pipe ID, as returned by pipe.open().
Return values
<>0 end-of-file indicator read on specified pipe
0 end-of-file indicator not read
Context
Bshell function.
Syntax
long pipe.error( long pipe_id )
Description
This checks the error indicator on the specified pipe to determine whether an error has occurred when reading or writing to the pipe. Note that the error indicator lasts until the pipe is closed, unless you explicitly clear it by calling
Functions reference
24-6
Interprocess communication (OS level)
Arguments
pipe_id
The pipe ID, as returned by pipe.open().
Return values
<>0 error has occurred when reading or writing to the pipe
0 no error has occurred
Context
Bshell function.
Syntax
long pipe.flush( long pipe_id )
Description
This writes any buffered data associated with a pipe to the related file. The stream remains open.
Arguments
pipe_id
The pipe ID, as returned by pipe.open().
Return values
0
-1 success error; most probably no connected stream on pipe_id
Context
Bshell function.
Functions reference
24-7
Interprocess communication (OS level)
Syntax
long pipe.gets( ref string line(80), long nr_of_bytes, long pipe_id )
Description
This reads a maximum of one line from the specified pipe.
Arguments
line
This stores the characters read from the pipe.
nr_of_bytes
This specifies the maximum number of bytes to be read from the pipe. The function stops reading when it encounters a newline character or when it has read the number of bytes specified by this argument, whichever comes first.
pipe_id
The pipe ID, as returned by pipe.open().
Return values
0
-1 success error; most probably no connected stream on pipe_id
Context
Bshell function.
Syntax
long pipe.open( string pathnm(128), string openmode(2) )
Description
This creates a UNIX process with the specified name and links an input and/or output stream to it. It returns a pointer to the pipe; this is used to identify the pipe in subsequent operations.
Functions reference
24-8
Interprocess communication (OS level)
Arguments
pathnm
The path name for the UNIX process.
openmode
Use this to specify whether the pipe is opened for reading, writing, or both. The possible values are:
"r" create for reading
"w" create for writing
"rw" create for reading and writing
Return values
>=1 success; a pointer to the pipe is returned
<1 error; that is, the negative value of the system error (for example, for a permission error, the system returns 13 and the function returns -13, or if the internal table is full, the function returns -EAGAIN).
Context
Bshell function.
Syntax
long pipe.puts( string line(80), long pipe_id )
Description
This writes data to the specified pipe. It automatically appends a newline character to the data.
Arguments
line
The data to be written to the pipe.
pipe_id
The pipe ID, as returned by pipe.open().
Return values
0
-1 success error; most probably no connected stream on pipe_id
Functions reference
24-9
Interprocess communication (OS level)
Context
Bshell function.
Syntax
long pipe.read( ref string buffer(1024), long nr_of_bytes, long pipe_id )
Description
This reads a specified number of bytes from the specified pipe.
Arguments
buffer
This stores the characters read from the pipe.
nr_of_bytes
This specifies the maximum number of bytes to be read from the pipe. The function stops reading when it has read the number of bytes specified by this argument or when it reaches the end of the file, whichever comes first.
pipe_id
The pipe ID, as returned by pipe.open().
Return values
>0 the number of bytes read
0 end-of-file
-1 error; most probably no connected stream on pipe_id
Context
Bshell function.
Functions reference
24-10
Interprocess communication (OS level)
Syntax
long pipe.write( string buffer(1024), long nr_of_bytes, long pipe_id )
Description
This appends a specified number of bytes to the specified pipe.
Arguments
buffer
This stores the characters that must be written to the pipe.
nr_of_bytes
This specifies the maximum number of bytes to be written to the pipe. The function stops writing to the pipe when it has written this number of bytes or when it reaches the end of the file, whichever comes first.
pipe_id
The pipe ID, as returned by pipe.open().
Return values
>0 the number of bytes written
0 end-of-file
-1 error; most probably no connected stream on pipe_id
Context
Bshell function.
Syntax
long recv.message( long key, long sender.key, long time, ref string message$ [, long fast] )
Description
This reads a message from the specified mailbox. The process must previously have connected to the mailbox by calling open.message().
Functions reference
24-11
Interprocess communication (OS level)
Arguments
key
The mailbox key, as returned by open.message().
sender.key
Messages sent with the send.message() function have an associated sender key which identifies the sender. To retrieve the next message from a particular sender, specify that sender’s key here. Otherwise specify zero – in this case the function retrieves the next message in the mailbox, regardless of the sender.
time message$ fast
Use this to specify the maximum time that the function must wait before returning. If you set this to -1, the function waits until a message arrives in the mailbox.
This stores the retrieved message.
Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Return values
This returns the sender key. It returns -1 if an error occurs (the predefined variable e contains the error number).
Context
Bshell function.
Syntax
long send.message( long dest.key, long sender.key, string message$ [, long fast]) )
Description
This stores a message in the specified mailbox. The process must previously have connected to the mailbox by calling open.message().
Functions reference
24-12
Interprocess communication (OS level)
Arguments
dest.key
The mailbox key, as returned by open.message().
sender.key
This is a unique key that identifies the sender of the message.
Processes reading from the mailbox can use this filter out messages from other senders.
message$ fast
This is the message to be sent to the mailbox.
Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Return values
This returns 0 when successful. Otherwise it returns an error number.
Context
Bshell function.
Functions reference
24-13
Interprocess communication (OS level)
Functions reference
24-14
Use these functions to perform mathematical operations of various types – for example: n n n n n n n n
To perform logarithmic and square root calculations
To perform geometrical calculations (cosine, sine, tangent, and so on)
To perform rounding operations
To compare values and return the maximum or minimum
To set variables to their maximum or minimum values
To calculate the absolute value of numeric expressions
To convert floating point expressions to integer values
To compare the values of two doubles to determine if they are equal.
double double double double double double long double double long double double long double double double abs acos asin atan cos
( num_expr )
( double x )
( double x )
( double x )
( double x ) cosh double.cmp
( double x )
( double double1, double double2, double tolerance )
( double x ) exp format.round
( double value, string format
[,long mode] ) int ( double_expr ) log log10 lpow max min pow
( double x )
( double x )
( long x, long y )
( double x, double y )
( double x, double y )
( double x, double y )
Functions reference
25-1
Mathematical operations
double void void void void double double double void double double round set.fmax
set.fmin
set.max
set.min
sin sinh sqrt table.round
tan tanh
( double value, long diga, long mode )
( variable [, string domain_name(.)] )
( variable [, string domain_name(.)] )
( variable [, string domain_name(.)] )
( variable [, string domain_name(.)] )
( double x )
( double x )
( double x )
( [field, field, ..., "table",
"table", ...] )
( double x )
( double x )
Syntax
double abs( num_expr )
Description
This returns the absolute value of the specified numeric expression. The expression can be of type integer or floating point.
Return values
The absolute value of the numeric expression.
Context
Bshell function.
Functions reference
25-2
Mathematical operations
Syntax
double acos( double x )
Description
This computes the arc cosine of x. The value of x must be in the range [-1, 1].
Return values
The arc cosine of x, expressed as a floating point number in the range [0,
π
] radians.
Context
Bshell process.
Syntax
double asin( double x )
Description
This computes the arc sine of x. The value of x must be in the range [-1, 1].
Return values
The arc sine of x, expressed as a floating point number in the range [-
π
/2,
π
/2] radians.
Context
Bshell function.
Functions reference
25-3
Mathematical operations
Syntax
double atan( double x )
Description
This computes the arc tangent of x.
Return values
The arc tangent of x, expressed as a floating point number in the range [-
π
/2,
π
/2] radians.
Context
Bshell function.
Syntax
double cos( double x )
Description
This computes the cosine of x, in radians. The x argument can be a long or a double.
Return values
The cosine of x.
Context
Bshell function.
Functions reference
25-4
Mathematical operations
Syntax
double cosh( double x )
Description
This computes the hyperbolic cosine of x.
Return values
The hyperbolic cosine of x.
Context
Bshell function.
Syntax
long double.cmp( double double1, double double2, double tolerance )
This compares two doubles to determine whether or not their values are equal.
Arguments
double1 double2
A double value.
A double value.
tolerance
Specifies a tolerance value for the function. If the difference between the two doubles is less than this value, the doubles are considered equal. Do not use a tolerance of 0.
Return values
0
-1
1 the difference between the doubles is less than the tolerance
double1 is less than double2 (the difference is greater than the tolerance)
double1 is greater than double2 (the difference is greater than the tolerance)
Functions reference
25-5
Mathematical operations
Context
Bshell function.
Example
double doub1, doub2 if not double.cmp( doub1, doub2, 0.0001 ) then
| the two doubles are equal
.....
endif
Syntax
double exp( double x )
Description
This returns the exponent of x. That is, it computes the value of the mathematical constant e (2.7182818) raised to the power of x.
Return values
The exponent of x.
Context
Bshell function.
Syntax
double format.round( double value, string format [,long mode] )
Description
The rounds a value according to a specified format.
Functions reference
25-6
Mathematical operations
Arguments
value
The value to be rounded.
format
The format for the returned value. For example
%10.5f
or
%5.10g
.
See sprintf$().
mode
This argument is optional. If it is not included, the default mode is 1.
0: truncate (for example, both 1.5 and 1.49 are rounded down to 1)
1: normal round (for example, 1.5 is rounded up to 2; 1.49 is rounded
down to 1)
2: round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values
The rounded value.
Context
Bshell function.
Syntax
long int ( double_expr )
Description
This converts the result of a floating point expression to an integer value. It returns only the integer portion of the result.
If the result of double_expr is positive, it is incremented by 0.0000001 before conversion. If the result is negative, it is decremented by 0.0000001 before conversion. This is done to avoid rounding problems.
Note
Assigning a floating point value to a variable of type long also converts a floating point value to an integer. But, in this case, the value is not incremented or decremented before truncation.
Return values
The integer result.
Functions reference
25-7
Mathematical operations
Context
Bshell function.
Syntax
double log( double x )
Description
This computes the natural logarithm of x. The value of x must be greater than zero.
Return values
The log of x.
Context
Bshell function.
Syntax
double log10( double x )
Description
This computes the base 10 logarithm of x. The value of x must be greater than zero.
Return values
The base 10 log of x.
Context
Bshell function.
Functions reference
25-8
Mathematical operations
Syntax
long lpow( long x, long y )
Description
This computes the value of x raised to the power of y. The y argument must be positive.
Return values
The value of x to the power of y. If y is zero, the return value is always 1.
Context
Bshell function.
Syntax
double max( double x, double y )
Description
This compares the values of the two arguments and returns whichever is the greatest. The arguments can be of type long or double or can contain any numeric expression.
Return values
The greatest of the two values.
Context
Bshell function.
Functions reference
25-9
Mathematical operations
Syntax
double min( double x, double y )
Description
This compares the values of the two arguments and returns whichever is the smallest. The arguments can be of type long or double or can contain any numeric expression.
Return values
The lesser of the two values.
Context
Bshell function.
Syntax
double pow( double x, double y )
Description
This computes the value of x raised to the power of y. If x is zero, y must be positive. If x is negative, y must be an integer.
Return values
The value of x to the power of y. If y is zero, the return value is always 1.0.
Context
Bshell function.
Functions reference
25-10
Mathematical operations
Syntax
double round( double value, long diga, long mode )
Description
This rounds a given value to a specified number of decimal places.
Arguments
value
The value to be rounded.
diga
The number of decimal places to which value is to be rounded.
mode
0
1
2 truncate (for example, both 1.5 and 1.49 are rounded down to 1) normal round (for example, 1.5 is rounded up to 2; 1.49 is rounded down to 1) round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values
The rounded value. Or the original value (value) if an error occurs.
Because the return value is of type double, the number of digits after the decimal sign is always 6. For example, round(1.345, 2, 1) returns 1.350000.
Context
Bshell function.
Functions reference
25-11
Mathematical operations
Syntax
void set.fmax( variable [, string domain_name(.)] ) void set.fmin( variable [, string domain_name(.)] ) void set.max( variable [, string domain_name(.)] ) void set.min( variable [, string domain_name(.)] )
Description
These set a specified variable to its maximum or minimum value. Use set.max() and set.min() for standard variables. Use set.fmax() and set.fmin() for multibyte strings.
Arguments
variable
The name of the variable to be set. This can be a single variable or an array.
domain
This argument is optional. It specifies the domain name of the variable. If this argument is included, the variable is set to the maximum or minimum value of the domain.
Notes
This table shows the maximum and minimum values of variable types supported by BaanERP.
byte/enumerated
0 integer -32768 long/set/date/text/time -2147483648
127
32767
2147483647 float double string[1] enumerated/set date time
-999999999999.9e20
-999999999999.9e64
chr(1)
1
0
0
999999999999.9e20
999999999999.9e64
"~" (max length 1024) depends on set definition
3652059
2147483647
Functions reference
25-12
Mathematical operations
multibyte string
configurable using the TSS dictionary programs
(session: Maintain Locale
Data)
configurable using the
TSS dictionary programs
(session: Maintain
Locale Data)
Context
Bshell functions.
Example
long value set.min( value ) | value contains -2147483648
Syntax
double sin( double x )
Description
This computes the sine of x, in radians. The x argument can be a long or a double.
Return values
The sine of x.
Context
Bshell function.
Syntax
double sinh( double x )
Description
This computes the hyperbolic sine of x.
Functions reference
25-13
Mathematical operations
Return values
The hyperbolic sine of x.
Context
Bshell function.
Syntax
double sqrt( double x )
Description
This computes the non-negative square root of x. The x argument must not be less than zero. It can be of type long or double.
Return values
The non-negative square root of x.
Context
Bshell function.
Syntax
void table.round( [field, field, ..., "table", "table",
...] )
Description
This rounds the values in certain tables and table fields according to parameters defined in the domain definition in the data dictionary.
Functions reference
25-14
Mathematical operations
Arguments
(no arguments) field [, field] …
The function rounds all fields of the main table.
The names of one or more table fields. The function rounds the values in all specified fields.
table [, table] …
The names of one or more tables. The function rounds all fields in the specified tables. You must specify table names within quotes – for example, tpctst999 .
Note
You can specify any combination of tables and fields, in any order.
Context
Bshell function.
Examples
table.round() | Rounds all fields of main table table.round(pctst999.price, "tpctst888", pctst999.value)
| Rounds the two specified fields and
| all fields of the specified table
Syntax
double tan( double x )
Description
This computes the tangent of x, in radians. The x argument can be a long or a double.
Return values
The tangent of x.
Context
Bshell function.
Functions reference
25-15
Mathematical operations
Syntax
double tanh( double x )
Description
This computes the hyperbolic tangent of x.
Return values
The hyperbolic tangent of x.
Context
Bshell function.
Functions reference
25-16
Use these functions to perform various memory operations. For example: n n n n
To allocate and deallocate memory at run time
To compare the values in two memory spaces
To copy data from one memory space to another
To set the content of a memory space.
long alloc.mem
void long void void long array.info
cmp.mem
copy.mem
free.mem
set.mem
( ref variable, long dim1 [, long dim2, ...] )
( void var, ref long nr.dims, ref long dim.array(4) )
( var1, var2 [, long count] )
( ref destination, source [, long count])
( variable )
( ref destination, source [, long count])
Syntax
long alloc.mem( ref variable, long dim1 [, long dim2, ...])
Description
This allocates memory space to the specified variable at run time (up to a maximum of 5Mb). The variable can be a string or an array (of any type). It must be declared as BASED. With multi-dimensional arrays, each dimension must be initialized to 1 at declaration. Once alloc.mem() has allocated memory for a variable, that variable behaves in the same way as any other variable.
Functions reference
26-1
Memory operations
When you call alloc.mem() a second time for the same variable, information already present is retained, but the variable is reallocated to a different part of memory. This is relevant only if you want to increase or decrease the memory space assigned to an array. Because the contents of array elements are contiguous in memory, you can change only the number of elements in the array (the first index in the case of longs and doubles; the second index in the case of strings).
Changing the size of array elements during reallocation causes loss of information.
Note
Remember to use free.mem() to deallocate memory space when it is no longer required.
Return values
0
-1 success insufficient memory available
Context
Bshell function.
Example
long i, j, k string c(1) based string st(1,1) based double d(1,1,1) based alloc.mem(c, 10) alloc.mem(st, 20, 5)
| Allocate a string with length 10
| Allocate 5 strings of length 20 alloc.mem(d, 2, 5, 6) | Allocate an array of doubles
| with 3 dimemsions for i=1 to 2 for j=1 to 5 for k=1 to 6 d(i,j,k) = k*j endfor endfor endfor alloc.mem(d, 4, 5, 6) | Reallocate array of doubles alloc.mem(st, 20, 8) | Reallocate 8 strings
Functions reference
26-2
Memory operations
Syntax
void array.info( void var, ref long nr.dims, ref long dim.array(4) )
Description
This returns the number of dimensions in a specified array variable and the size of each dimension.
Arguments
var nr.dims, dim.array
The name of the array variable.
These return the number of dimensions in the array and the size of each dimension.
If var specifies a non-array variable, nr.dims returns 0 and
dim.array returns dim.array(1) = 0. If var specifies a string, such as s1(10), nr.dims returns 1 and dim.array returns dim.array = 10.
Example
long a3(3,5,7) string s3(3,5,7) long nr.dims
long dim.array(4) string b4(1,1,1,1) based array.info( a3, nr.dims, dim.array )
| Returns:
| nr.dims = 3
| dim.array(1) = 3
| dim.array(2) = 5
| dim.array(3) = 7 array.info( s3, nr.dims, dim.array )
| Returns:
| nr.dims = 3
| dim.array(1) = 3
| dim.array(2) = 5
| dim.array(3) = 7
Functions reference
26-3
Memory operations
array.info( b4, nr.dims, dim.array )
| Returns:
| nr_dims = 4
| dim.array(1) = 0
| dim.array(2) = 0
| dim.array(3) = 0
| dim.array(4) = 0
Syntax
long cmp.mem( var1, var2 [, long count] )
Description
This compares the values of two variables or arrays. By default, the values are compared for the length of the shortest argument. If you specify the optional
count argument, the function compares the first count digits or characters of both arguments.
Return values
The return values depend on the types of the variables.
Variables are of different types:
1
Variables are longs or doubles:
0
1 values are equal values are different
Variables are strings or arrays of type long, double, or string:
<0
=0
>0 first argument is less than second arguments are equal first argument is greater than second
Context
Bshell function.
Functions reference
26-4
Memory operations
Example
long l_arr(2,2), lng_arr(3,5), ret fill_long_arrays() ret = cmp.mem( lng_arr, l_arr ) | The first 4 elements
| are checked if ret = 0 then message( "values are equal" ) else if ret > 0 then message( "First array greater than second" ) else endif message( "First array less than second" ) endif
Syntax
void copy.mem( ref destination, source [, long count] )
Description
This copies the memory space from the source argument to the destination argument. By default, the total length of source is copied. But, if the destination argument is shorter than the source argument, then source is truncated. Use the optional count argument to copy a specified number of bytes only.
You can use this function to copy single variables or entire arrays. You cannot copy variables of different types. It you attempt to do this, the destination argument remains unchanged.
Context
Bshell function.
Functions reference
26-5
Memory operations
Example
long i,j long src(5,5) long des(3,3) for i=1 to 5 for j=1 to 5 src(i,j)=i*j endfor endfor copy.mem(des,src) | des contains the first 9 elements
| of src
Syntax
void free.mem( variable )
Description
This deallocates memory space previously allocated to the specified variable by
variable cannot be used again after deallocation, unless it is reallocated memory space again using alloc.mem().
Context
Bshell function.
Syntax
long set.mem( ref destination, source [, long count] )
Description
The stores the value of source in the destination argument. By default, the value of source is repeated in destination until the latter is completely filled. Use the optional count argument to repeat the value of source a specific number of times only. Elements in the destination argument which are not overwritten remain unchanged.
Functions reference
26-6
Return values
0
-1 success error
Context
Bshell function.
Example
| To set a string array to spaces string string_array(20, 5, 5) long ret ret = set.mem( string_array, "" )
| To store a long in a string string str1(20) long ret ret = set.mem( str1, "10", 5 )
| str1 now contains "1010101010"
Memory operations
Functions reference
26-7
Memory operations
Functions reference
26-8
Use these functions for handling status messages, error messages, and other messages that are output to the screen or to a log file.
4GL programs (except type 4 programs) usually display a status area consisting of four status fields. The standard program uses all four fields. 4GL programs can display messages in the first two fields (see the status functions below).
1
2
3
4
15
15
3
3
application dependent/database action field type during input / zoom
Caps Lock key status
Num Lock key status
void void long long void clean.mess
dal.count.error.
messages
( )
( ) dal.get.error.message
( ref string msg ) dal.get.first.error.
message
( ref string msg, ref string code ) dal.reset.error.
messages
( long amt ) void dal.set.error.message
( string mess.or.code [, arg ...] ) string form.text$ ( string messcode(14) [, string language code ] ) void mess void message
( string messcode(14), long mode [, arg, ...] )
( string mess_str(.) [, arg, ...] )
Functions reference
27-1
Message handling
void void void void void void set.input.error
status.del
status.field
status.mess
status.off
status.on
( string messcode(14) [,
...] )
( )
( long fieldnr, string strg(15) )
( string strg(15) )
( [long mode] )
( [long mode] )
Syntax
void clean.mess()
Description
This removes a message that was displayed by using the mess() function with its mode argument set to 0.
Context
3GL library function.
Syntax
void dal.count.error.messages()
Description
This returns the number of DAL error messages currently in the message buffer.
Context
DAL function.
Functions reference
27-2
Message handling
Syntax
long dal.get.error.message(ref string msg)
Description
This retrieves the next DAL error message from the message buffer. It retrieves the messages on a last-in-first-out (LIFO) basis.
Return value
The number of messages that remain in the message buffer.
Context
DAL function.
This function is provided for use by external applications. It is not normally used in DAL or UI scripts.
Syntax
long dal.get.first.error.message(ref string msg, ref string code)
Description
This retrieves the first available DAL error message from the message buffer, together with the message code. It retrieves the messages on a first-in-first-out
(FIFO) basis. The message is removed from the buffer.
Note that FIFO message retrieval is slightly slower than LIFO message retrieval.
Return value
The number of messages that remain in the message buffer.
Context
DAL function.
Functions reference
27-3
Message handling
Syntax
void dal.reset.error.messages(long amt)
Description
This clears DAL error messages from the message buffer.
Arguments
amt
0 clear the entire buffer
>0 clear all but the specified number of messages; the most recent messages are the messages that are cleared
<0 clear the specified number of the most recent messages
Context
DAL function.
Examples
If there are 6 messages in the message buffer, the following examples have the same result: dal.reset.error.messages(-4) | clears the 4 most recent
| messages dal.reset.error.messages(2) | clears all but the 2 oldest
| messages
Syntax
void dal.set.error.message(string mess.or.code [, arg ...])
Description
Use this to set an error message to be displayed by the standard program or by external applications when a DAL hook returns a negative value.
Functions reference
27-4
Message handling
Arguments
mess.or.code
Specifies either the data dictionary code for the message or a literal string. In the latter case, the value of mess.or.code must start with the at sign [@]. Note that using a literal string makes the script language dependent.
arg ....
Use these optional arguments to pass arguments to the
mess.or.code variable.
Context
DAL function.
Syntax
string form.text$( string messcode(14) [, string language_code ] )
Description
This retrieves a message from the data dictionary. It is used for constructing strings with parameter substitution. For messages to the screen, use mess().
Arguments
messcode
The message code of the required message.
language_code
The language code. If you do not specify a language code, the user language is used. Otherwise the message with the specified language is retrieved (if available).
Return value
The message string.
Context
3GL library function.
Functions reference
27-5
Message handling
Example
| Suppose there is a message code "pcgen00016" in the data
| dictionary with the text "Error %d in file %s".
string error(80) long lfn_log lfn_log = seq.open("./err.log", "a") | Open for adding text error = form.text$("pcgen00016")
| error now contains "Error %d in file %s" error = sprintf$(error, e, filename$)
| error now contains, for example "Error 13 in file
| tttmir001" seq.puts( error, lfn_log ) | Writes error to file "err.log" seq.close( lfn_log )
Syntax
void mess( string messcode(14), long mode [, arg, ...] )
Description
This retrieves a message from the data dictionary and displays it on screen. Using this function makes your program script language independent.
Arguments
messcode
The message code (including the package code). The language code of the user is automatically added. Both the message code and the user language must be available in the data dictionary.
mode
This specifies how the message can be removed:
1 The message is displayed in a separate window and the user must click a button in that window to remove the message.
arg ...
0 The message is displayed on the status bar. The user cannot remove the message. It remains until removed by the
The message string in the data dictionary can contain format characters for parameter substitution. The values which must be substituted are specified in the 3rd, 4th, ... arguments of the function. The number of these arguments is variable.
Functions reference
27-6
Message handling
Note
In 3GL scripts, the variable graphical.mode must be set to 1 if you want the message to be displayed in a separate window.
Context
3GL library function.
Example
| Suppose there is a message code "pcgen00016" in the data
| dictionary with the text "Error %d in file %s" mess("pcgen00016",1,e,filename$) mess("pcgen00016",0,e,filename$)
| Prompt for ENTER
| Display message and
| continue (if there
| is a current form)
Syntax
void message( string mess_str(.) [, arg, ...] )
Description
This displays the specified message string on screen.
In character-based windows, the message is displayed on the message line of the window. The message "PRESS <RETURN>" is displayed at position 61 of that line. If mess_str is longer than 60 characters, a window is created at the foot of the screen to display the message. In graphical forms, a separate window is created.
The system removes the message when the user presses ENTER or clicks a button.
Functions reference
27-7
Message handling
Arguments
mess_str
The message string to be displayed. This can contain format characters for parameter substitution. For details about formatting a string see sprintf().
arg ...
The message string can contain format characters for parameter substitution. The values which must be substituted are specified in the 2nd, 3rd, ... arguments of the function. The number of these arguments is variable.
Note
Using message() makes your program script language dependent. If you require language independency, use mess() instead.
Context
3GL library function.
Example
| Suppose the user enters a non-existent code 123 (from
| pctst999.item) and you want to display the message:
| "Code (123) not found." message("Code (123) not found.")
| However it is better to use parameter substitution: message("Code (%d) not found.", pctst999.item)
| The following construction gives the message "Error 13 in
| file tpctst999", for example: message("Error %d in file %s", e, filename$)
Functions reference
27-8
Message handling
Syntax
void set.input.error( string messcode(14) [, arg, ...] )
Description
This causes the standard program to display the specified error message and to force input again in the same input field. If you specify an empty string, no error message is displayed.
Arguments
messcode
The message code of the required message. This must be defined in the data dictionary. This argument can contain format characters for parameter substitution.
arg ...
The messcode argument can contain format characters for parameter substitution. The values which must be substituted are specified in the 2nd, 3rd, ... arguments of the function. The number of these arguments is variable.
For details about formatting a string see sprintf().
Notes
You can use set.input.error() only in check.input event sections of a 4GL script. The error message is displayed after the entire section has been executed.
Consequently, you cannot display two error messages with this function. The predefined variable stp.check.input.error indicates whether set.input.error() has been called.
Before a choice.update.db (except at delete) section, all check.input sections of all fields are executed. If one error is set with set.input.error(), the remaining sections are not executed. In a type 4 program, which does not support
section. With the predefined variable before.update.check (read-only), you can control if the input check is executed before update or during input.
Context
4GL library function. You can use this function only in 4GL scripts, and only in
Functions reference
27-9
Message handling
See also
dal.set.error.message
Example
field.pctst900.item: check.input: if before.update.check then set.input.error("pctsts0001") | before update else set.input.error("pctsts0002", e) | during input endif
Syntax
void status.del()
Description
This clears the first status field in the status area.
Context
3GL library function.
Syntax
void status.field( long fieldnr, string strg(15) )
Description
This displays the specified message string in a specified status field of a 4GL form.
In previous BAAN releases, there were 5 status fields, numbered 1to 5. Status fields 1 to 4 in the current release correspond to fields 2 to 5 in previous releases.
This function uses the old numbering system. For example: status.field( 2, "replace" ) | displays message in 1st field status.field( 3, "replace" ) | displays message in 2nd field
Functions reference
27-10
Message handling
Note
This function is supported for backward compatibility only. To display a message in the first status field, use status.mess() instead.
Context
Bshell function.
Syntax
void status.mess( string strg(15) )
Description
This displays the specified message in the first status field of a 4GL form.
Context
3GL library function.
Syntax
void status.off( [long mode] )
Description
This disables the status line on a 4GL form. The line remains on the screen, but it does not display any subsequent status messages.
Arguments
mode
By default, the status line is disabled for the current process only. To disable the status line for all processes of the current main window, set this optional argument to 1.
Context
Bshell function.
Functions reference
27-11
Message handling
Syntax
void status.on( [long mode] )
Description
This enables the status line on a 4GL form after it has been disabled by
Arguments
mode
By default, the status line is enabled for the current process only. To enable the status line for all processes of the current main window, set this optional argument to 1.
Context
Bshell function.
Functions reference
27-12
Use these functions for handling multibyte strings.
The characters sets used in some parts of the world require more than a single byte per character. BAAN software provides multibyte character support via the
BAAN Super Set (TSS). TSS is a super set of both ASCII and multibyte character sets. In TSS, a character can occupy from one to four bytes, as required. Multibyte characters always start with the escape code 0x9b. So they can always be recognized within a string.
See also Chapter 41, String operations.
string string long long long mb.cast$ mb.cast.to.str$ mb.char
mb.char.info
mb.display
long long long long long long string string string long string mb.export$ mb.ext.clean$ mb.hasbidi
mb.import$ mb.isbidi
mb.isbidi.
language mb.locale.info
mb.localename$ mb.long.to.str$ mb.nsets
mb.rev$
( string_expr )
( string_expr )
( long charvalue )
( string ch$ )
( string_expr, ref string substr$, long space, [, long flags] )
( string target$, string source$
[, long setid ] )
( ref string ext.string )
( string_expr )
( string target$, string source$
[, long setid ] )
( )
( string lang )
( long info_flag )
( )
( long charvalue )
( )
( string_expr [, long flags] )
Functions reference
28-1
Multibyte strings
long long long long long long mb.scrpos
mb.set.info
mb.strpos
mb.tss.clean$ mb.type
mb.width
( string_expr, long pos )
( long setid, ref string name, ref string desc, ref long n_items )
( string_expr, long pos )
( ref string tss.string )
( string_expr )
( string_expr )
Syntax
string mb.cast$( string_expr )
Description
This converts a specified string to a multibyte string. The content of the string remains the same.
Return values
The multibyte string.
Context
Bshell function.
Syntax
string mb.cast.to.str$( string_expr )
Description
This converts a specified string to a single-byte string. The content of the string remains the same.
Return values
The single-byte string.
Functions reference
28-2
Multibyte strings
Context
Bshell function.
Syntax
long mb.char( long charvalue )
Description
This function tests if a specified character code represents a multibyte character.
It is mainly used in conjunction with the next.event() function, which returns a character as a long value.
Return values
2
1
0
charvalue is a multibyte character
charvalue is an ISO-8859/1 character
charvalue is some other key (for example, a function key)
Context
Bshell function.
Example
This example filters out function keys but processes other characters.
long event(EVTMAXSIZE), ch ch = evt.keypress.key(event) if mb.char(ch) then mb.long.to.str$( evt.keypress.key(event) )
| manage characters endif
Functions reference
28-3
Multibyte strings
Syntax
long mb.char.info( string ch$ )
Description
This identifies the character set to which a TSS character belongs. It returns the character set ID for the first character in the specified string.
In TSS, it is possible that several characters convert to one internal TSS area
(parts of SHIFT-JIS and KANJI_EUC both convert to one command area; that is,
JIS). In that case, the function returns the lowest of the character set IDs. For example, if SHIFT-JIS has the character set code 1, and KANJI-EUC has the code 2, then the function returns 1.
Return values
The ID of the character set for the first character in the specified string. Or -1 if
ch$ is an empty string or if the TSS character could not be found in one of the
TSS character sets.
Context
Bshell function.
Syntax
long mb.display( string_expr, ref string substr$, long space [, long flags] )
Description
This returns that part of a specified string that fits in a specified display space.
The substring is equal to the source string if the source string fits in the display space. If one or more characters do not fit in the display space, a ghost character
(default is >) is appended to the substring.
Functions reference
28-4
Multibyte strings
Arguments
string_expr
The source string.
substr$
The returned substring. This ends with a ghost character if some characters of the source string do not fit in the specified display space.
space flags
The size of the display space for the substring.
These optional flags specify certain criteria for handling the substring. They are particularly useful for working with bidirectional strings.
TSS_REVERSE
Reverse the substring if the current user environment is bidirectional and if string_expr contains bidirectional characters. The substring is ready for display.
TSS_FILLOUT
Fill the substring with trailing spaces, so that the width of the string equals the display space. This is the default if no flags are specified.
TSS_FORCE_REVERSE
Reverse the substring if string_expr contains bidirectional characters. The substring is ready for display.
TSS_FILTER_ESC
Filter out escape sequences.
TSS_FILTER_CF
Filter out code features.
Return values
An index to omitted characters if the string is truncated. Otherwise, the length of the string.
Context
Bshell function.
Functions reference
28-5
Multibyte strings
Syntax
long mb.export$( string target$, string source$ [, long setid ] )
Description
This converts a string from the TSS character set to the external, native character set. By default, the setting of the current locale determines the character set to which the string is converted. Code features in the string are skipped.
Arguments
target$
The converted string. This can be a maximum of 1024 bytes.
source$
The source string that must be converted.
setid
If you do not want to base the conversion on the setting of the current locale, use this optional argument to specify the ID of the
TSS character set to be used in the export operation.
Return values
> 0 the number of converted bytes
-1 the target string was too small to contain the converted string
-2 an incomplete character was found at the end of the string
-3 character could not be converted.
Context
Bshell function.
Syntax
long mb.ext.clean$( ref string ext.string )
Description
This replaces characters in a specified string with spaces, if those characters cannot be converted from native format to TSS.
Functions reference
28-6
Multibyte strings
Return values
>0
0 the position of the first character that could not be converted all characters can be converted.
Context
Bshell function.
Syntax
long mb.hasbidi( string_expr )
Description
This checks whether a specified string contains at least one bidirectional character. The function works regardless of the current user locale.
Return values
TRUE string contains a bidirectional character
FALSE string does not contain a bidirectional character
Context
Bshell function.
Syntax
long mb.import$( string target$, string source$ [, long setid ] )
Description
This converts a string from the external, native character set to the TSS character set. By default, the setting of the current locale determines the native character set from which the string is converted.
Functions reference
28-7
Multibyte strings
Arguments
target$
The converted string. This can be a maximum of 1024 bytes.
source$
The source string that must be converted.
setid
If you do not want to base the conversion on the setting of the current locale, use this optional argument to specify the ID of the
TSS character set to be used in the import operation.
Return values
> 0 the number of converted bytes
-1 the target string was too small to contain the converted string
-2 an incomplete character was found at the end of the string
-3 character could not be converted.
Context
Bshell function.
Syntax
long mb.isbidi( )
Description
This checks whether the current environment is a bidirectional one.
Return values
TRUE current environment is bidirectional
FALSE current environment is not bidirectional
Context
Bshell function.
Functions reference
28-8
Multibyte strings
Syntax
long mb.isbidi.language( string lang )
Description
This checks whether the specified language is a bidirectional one. To use the function, you must link to the ttdllbidi library. The function checks the flag
‘%[email protected]’ in the table ‘%TB@ttaad110’.
Return values
TRUE current language is bidirectional
FALSE current language is not bidirectional
Context
Bshell function.
Syntax
string mb.locale.info( long info_flag )
Description
This returns information about the current locale.
Arguments
info_flag
Specifies the required information. The possible values are:
TSS_GET_LOCALE_NAME
TSS_GET_NLS_NAME
TSS_GET_TSS_NAME
TSS_GET_IFACTOR
TSS_GET_EFACTOR returns the locale name returns the NLS name returns the name of the character set returns the internal mb factor returns the external
(database) factor
Functions reference
28-9
Multibyte strings
Return values
A string containing the requested information.
Context
Bshell function.
Syntax
string mb.localename$( )
Description
This returns the name of the current locale as defined in the file
’$bse/lib/user/u<user>'. The file ‘$BSE/lib/tss_localex.x’ (where x.x is the bshell version) contains all locales that the system supports.
Context
Bshell function.
Syntax
string mb.long.to.str$( long charvalue )
Description
This converts a character code to the equivalent string value. It accepts ISO-
8859/1 and multibyte character codes only. Do not use it for other characters, such as function keys.
Return values
string success empty string illegal character code (an error message is logged)
Context
Bshell function.
Functions reference
28-10
Multibyte strings
Example
See mb.char().
Syntax
long mb.nsets( )
Description
This returns the number of TSS character sets currently defined. This is useful for retrieving character set information using mb.set.info().
Context
Bshell function.
Example
See mb.set.info().
Syntax
string mb.rev$( string_expr [, long flags] )
Description
This reverses the order of the characters in a specified string.
Functions reference
28-11
Multibyte strings
Arguments
string_expr
The source string.
flags
By default, this function reverses the string, whether or not the current user locale is bidirectional. Use these optional flags to override this default situation:
TSS_REVERSE reverse string only if it contains bidirectional characters and the current locale is bidirectional
TSS_FORCE_REVERSE reverse string only if it contains bidirectional characters
Notes
The order of ASCII characters does not change. Code features are treated as separators and their position does not change. For example:
Source string: h1, h2, and h3 are bidirectional characters h1 h2 h3 A B C cf(0) D E F
Reversed string: Hebrew/Arabic
D E F cf(0) A B C h3 h2 h1
Return values
The reversed string.
Context
Bshell function.
Examples
x = mb.rev$( y ) | reverses always x = mb.rev$( y, TSS_REVERSE )
| reverses when current locale is
| bidirectional and y contains bidirectional characters if mb.hasbidi( y ) then x = mb.rev$( y ) | reverses when y contains
| bidirectional characters endif
Functions reference
28-12
Multibyte strings
Syntax
long mb.scrpos( string_expr, long pos )
Description
This converts a string position to a screen position. Code features are ignored.
Arguments
string_expr
The source string.
pos
A position in the string.
Return values
The screen position corresponding to the specified string position. Or -1 if pos lies beyond the end of the string.
Context
Bshell function.
Syntax
long mb.set.info( long setid, ref string name, ref string desc, ref long n_items )
Description
This returns information about a specified character set.
Arguments
setid name desc
The character set ID.
The name of the character set.
The description of the character set.
n_items
The number of defined ranges in the character set.
Functions reference
28-13
Multibyte strings
Return values
0
-1 success the set ID is not linked to a known character set
Context
Bshell function.
Example
long id, nr, n_items string name(20), desc(80) nr = mb.nsets() for id = 0 to nr if mb.set.info( id, name, desc, n_items ) <> -1 then print name, cr$(), lf$() endif endfor
Syntax
long mb.strpos( string_expr, long pos )
Description
This converts a screen position to a string position. Code features are ignored.
Arguments
string_expr
The source string.
pos
A screen position.
Return values
The string position corresponding to the specified screen position. Or -1 if pos lies beyond the end of the string.
Context
Bshell function.
Functions reference
28-14
Multibyte strings
Syntax
long mb.tss.clean$( ref string tss.string )
Description
This replaces characters in a specified string with spaces, if those characters cannot be converted from TSS to native format.
Return values
0
>0 all characters can be converted the position of the first character that could not be converted.
Context
Bshell function.
Syntax
long mb.type( string_expr )
Description
This tests if a specified string is a multibyte string. It does not test the content of the string.
Return values
- 1
0 the string is not of type multibyte the string is of type multibyte
Context
Bshell function.
Functions reference
28-15
Multibyte strings
Syntax
long mb.width( string_expr )
Description
This returns the display width of a specified string; that is, the number of positions the string will occupy on the screen.
An ISO-8859/1 character has a display width of one screen position. A multibyte character has a display width of one or two screen positions.
Return values
The display width of the specified string.
Context
Bshell function.
Functions reference
28-16
The Plan Chart Manager is a graphical planning environment. You can use the
Plan Chart Manager functions to develop applications that create and manipulate plan charts within this environment; the Plan Chart Manager acts as the server for the applications.
The Plan Chart Manager provides a planning board, on which you can build and maintain plan charts on line. Users can open sessions in order to define and modify activities, relations between activities, and so on. The planning board consists of: n n n
A time scale.
Horizontal lines (the planning board lines), on which users can place activities.
Columns that describe the activities.
Activities are the building blocks of a plan. An activity is an event or series of actions, with a start and end time. On the planning board, activities are displayed as horizontal bars whose length represents the duration of the activity. The relations between the activities constitute the planning structure.
You can define a different time unit for each plan, to be used in the time scale displayed at the top of the planning board. In principle, you can use any time unit, from a second to a year, as the base unit. In practice, day, week, and month are normally used, the day being the base unit. If required, you can define several time scales for each plan.
Functions reference
29-1
Plan Chart Manager
The Plan Chart Manager communicates with a client application by means of events. Each user action within the Plan Chart manager generates an event. The client must include a loop to handle these events.
The Plan Chart manager generates the following event types:
PCM_EVTMENUSELECT Occurs when the user selects a menu item of the planning board.
PCM_EVTPUSHBUTTON
PCM_EVTOBJECTPRESS
Occurs when the user clicks on a button of the planning board.
Occurs when the user clicks on an activity, relation, or marker on the planning board.
PCM_EVTOBJECTDPRESS Occurs when the user double-clicks on an activity, relation, or marker.
PCM_EVTOBJECTMOVE Occurs when the user moves an activity, relation, or marker.
PCM_EVTCLOSED Occurs when the Plan Chart Manager is closed.
All colors must be composed by using the rgb() function. Or you can use one of the following predefined colors:
RGB.BLACK
RGB.BLUE
RGB.YELLOW
RGB.MAGENTA
RGB.GREEN
RGB.GRAY
RGB.RED
RGB.WHITE
RGB.CYAN
Functions reference
29-2
Plan Chart Manager
long void void long long void void void void void void pcm.activate.session
( ref string session(), ref string title() ) pcm.change
( long plan_id [, flag, value
] ... ) pcm.change.object
pcm.create
pcm.create.object
( long plan_id, long object_id
[, flag, value ] ... )
( [ flag, value ] ...)
( long plan_id, long pcm.destroy
pcm.destroy.object
pcm.get.data
pcm.lock
pcm.refresh
pcm.send.bms.event
object_type [, flag, value ]
... )
( long plan_id )
( long plan_id, long object_id)
( long evt_type, ref string arglist(), ... )
( long plan_id, long lock )
( long plan_id )
( long command, ref string arglist() )
Syntax
long pcm.activate.session( ref string session(), ref string title() )
Description
This starts a specified 4GL session. It generates a new window for the session and ensures that it is handled correctly. You can use this function in combination with pcm.send.bms.event(), which sends changed values back to the application as events.
Arguments
session
The session code.
title
The title for the session window.
Functions reference
29-3
Plan Chart Manager
Return values
The function returns the process ID of the activated session.
Context
3GL library function.
Example
See pcm.send.bms.event()
Syntax
void pcm.change( long plan_id [, flag, value ] ... )
Description
Use this function to change the attributes of a specified chart.
Arguments
plan_id
The ID of the chart whose attributes you want to change, as returned by pcm.create().
flag, value
Use these arguments to set new values for the chart attributes. For each attribute you specify, you must include the attribute type (for example, PcmPlanName or PcmPlanBackgroundColor), and the attribute value. For a list of the plan attributes, see pcm.create().
Context
3GL library function.
Functions reference
29-4
Plan Chart Manager
Syntax
void pcm.change.object( long plan_id, long object_id [, flag, value ] ... )
Description
Use this function to change the attributes of an object that was created by
Arguments
plan_id
The ID of the chart to which the object belongs, as returned by
The ID of the object, as returned by pcm.create.object().
object_id flag, value
Use these arguments to set new values for the object’s attributes.
For each attribute you specify, you must include the attribute type (for example, PcmMenuName or PcmTimescaleVisible), and the attribute value. For a list of the object attributes, see
Context
3GL library function.
Syntax
long pcm.create( [ flag, value ] ... )
Description
This starts the Plan Chart Manager and creates a new chart with the specified attributes. It returns the variable plan_id, which is a unique identifier for the chart. You use plan_id in the other functions in order to identify the chart you want to work with.
Functions reference
29-5
Plan Chart Manager
Arguments
The arguments of pcm.create() consist of a series of attribute-value pairs. Each of these specifies an attribute type and a value for that attribute. The attributes available are as follows:
The title of the chart.
PcmPlanName(50)
(string)
PcmPlanFontHeight
(long)
The size of the font used in the chart.
The distance between the lines/activities.
PcmPlanLineHeight
(double)
PcmPlanBackgroundColor
(long)
PcmPlanForegroundColor
(long)
PcmPlanProgressColor
(long)
PcmPlanActivityColor1 -
PcmPlanActivityColor9
(long)
PcmPlanRelationColor1 -
PcmPlanRelationColor9
(long)
PcmPlanMarkerColor1 -
PcmPlanMarkerColor3
(long)
PcmPlanCriticalColor
(long)
PcmPlanTimescaleStart
(double)
The background color for the chart.
The foreground color for the chart.
The color for the part of an activity that has been reported as completed.
Use these to define the colors for activity groups. You can define up to nine activity groups, and assign a different color to each.
Use these to define the colors for relation groups. You can define up to nine relation groups, and assign a different color to each.
Use these to define the colors for marker groups. You can define up to three marker groups, and assign a different color to each.
The color for an activity or relation that is part of the critical path.
The starting point of the time scale. Specify a number that you translate into a date or time value when dividing the time scale.
The end point of the time scale.
PcmPlanTimescaleFinish
(double)
PcmPlanTimescaleWidth
(double)
The width (number of characters) of each time unit on the time scale.
Functions reference
29-6
Plan Chart Manager
PcmPlanFreeTimeVisible
(long)
PcmPlanCriticalVisible
(long)
PcmPlanDelaysVisible
(long)
PcmPlanRelationsVisible
(long)
PcmPlanRelationsStraight
(long)
PcmPlanMarkersVisible
(long)
This indicates if the float must be displayed in the chart. The possible values are true or false.
Activities and relations that are part of the critical path can be shown in a particular color.
This flag indicates if the critical path must be displayed in the chart. The possible values are true or false.
You can define lay-offs, holidays, and weekends as non-workdays and the Plan Chart
Manager then takes this into account. This flag indicates if non-workdays must be shown hatched or not. The possible values are true or false.
You can define relations between different objects by means of lines on the planning board.
This flag indicates if the relations must be visible. The possible values are true or false.
true a relation is represented by a straight line between two objects false a relation is represented by lines at right angles or parallel to the objects
You can add a marker to an activity in order to plan certain standard actions – for example,
"Principal's Approval". This flag indicates if such markers must be visible in the planning board. The possible values are true or false.
Return values
The function returns a unique ID for the new chart.
Context
3GL library function.
Functions reference
29-7
Plan Chart Manager
Syntax
long pcm.create.object( long plan_id, long object_type [, flag, value ] ... )
Description
This creates an object of the specified type – for example, a menu item, an activity, a relation, or a marker.
The function returns the object_id, which in turn is used in the functions
to be changed or deleted. The object_id is also used in submenus and with subactivities in order to indicate the parent of the menu or activity.
Arguments
plan_id
The ID of the plan to which you want to add the new object.
object_type
The object type. The possible values are:
flag, value
PCM_OT_MENU
PCM_OT_DELAY
PCM_OT_COLUMN a menu item
PCM_OT_BUTTON a button to which you can link sessions or options
PCM_OT_TIMESCALE a time scale delay time (that is, non workdays) a column containing an activity description
PCM_OT_ACTIVITY
PCM_OT_RELATION an activity a relation
PCM_OT_MARKER an activity marker
Use these arguments to define the object's attributes. For each attribute you specify, you must include the attribute type (for example, PcmMenuName or PcmTimescaleVisible), and the attribute value. The attributes of each object are listed in the section describing that object.
Return values
The function returns a unique ID for the new object.
Functions reference
29-8
Plan Chart Manager
Context
3GL library function.
Syntax
void pcm.destroy( long plan_id )
Description
This ends the specified plan chart and removes all associated settings and objects.
Context
3GL library function.
Syntax
void pcm.destroy.object( long plan_id, long object_id )
Description
This deletes the specified object.
Arguments
plan_id
The ID of the chart to which the object belongs, as returned by
object_id
The ID of the object, as returned by pcm.create.object().
Context
3GL library function.
Functions reference
29-9
Plan Chart Manager
Syntax
void pcm.get.data( long evt_type, ref string arglist(),
...)
Description
When the client application receives an event from the Plan Chart Manager, use this function to read the event.
Arguments
evt_type
This specifies the type of the event you want to read.
arglist
This returns the argument list.
. . .
The third and subsequent arguments return individual event arguments. The number and meaning of the arguments depends on the event type.
PCM_EVTMENUSELECT 3rd argument – long menu_id
4th argument – long object_type
5th argument – long object_id
PCM_EVTPUSHBUTTON
PCM_EVTOBJECTPRESS
3rd argument – long button_id
4th argument – long object_type
5th argument – long object_id
3rd argument – long object_type
4th argument – long object_id
5th argument – double time
PCM_EVTOBJECTDPRESS 3rd argument – long object_type
4th argument – long object_id
5th argument – double time
PCM_EVTOBJECTMOVE 3rd argument – long object_type
4th argument – long object_id
5th argument – double start
6th argument – double finish
Context
3GL library function.
Functions reference
29-10
Plan Chart Manager
Syntax
void pcm.lock( long plan_id, long lock )
Description
Use this function to lock and unlock the Plan Chart Manager (for example, when data is changed in a session).
Arguments
plan_id
The ID of the planning chart that you want to lock.
lock
This indicates whether the planning chart must be locked or unlocked. The possible values are: true The planning board is locked. The user cannot interact with it until it is unlocked again.
false The planning board is unlocked. This is the default value.
Context
3GL library function.
Syntax
void pcm.refresh( long plan_id )
Description
This (re)draws the specified chart and updates the display with all new and changed objects.
Context
3GL library function.
Functions reference
29-11
Plan Chart Manager
Syntax
void pcm.send.bms.event(long command, ref string arglist())
Description
Use this in a process started by pcm.activate.session() in order to send an event back to the application that started the session.
Arguments
command
The command to be sent back to the application. The Chart
Manager places this in the variable evt.bms.command(event).
arglist
The argument list. The application can retrieve this string by calling bms.receive$().
Context
3GL library function.
Example
Application
| handle events while next.event(event) evt.bucket = bms.receive$() on case evt.bms.sender(event) case appl.pid: pcm.bucket = evt.bucket
if pcm.bucket(1;1) = "0" then item.f = pcm.bucket(2;16) item.t = pcm.bucket(18;16) else if pcm.bucket(1;1) = "1" then cprj.f = pcm.bucket(2;6) cprj.t = pcm.bucket(8;6) endif endif pcm.refresh(plan_id) break
Functions reference
29-12
Plan Chart Manager
case ...
....
endcase
....
endwhile
| start session tt.session.desc("ppmod1000m000", desc) appl.pid = pcm.activate.session("ppmod1000m000", desc)
Other process
choice.cont.process: before.choice: event.bucket(1;1) = "0" event.bucket(2;16) = item.f
event.bucket(18;16) = item.t
pcm.send.bms.event(0, event.bucket) choice.end.program: before.choice: event.bucket(1;1) = "1" event.bucket(2;6) = cprj.f
event.bucket(8;6) = cprj.t
pcm.send.bms.event(0, event.bucket)
Overview
On the planning board, you can create a menu structure that consists of one or more menu items. Users can click on these items to initiate actions, such as starting a session. Each part of the menu structure consists of a parent menu item and related child menu item(s). You must create a PCM_OT_MENU object for each menu item.
Attributes
PcmMenuParent
(long)
PcmMenuId
(long)
This indicates the object ID of the item’s parent item.
The parent ID of a parent menu item is 0.
The unique identification number of the menu item.
This is included in PCM_EVTMENUSELECT events, in order to identify the menu item to which the event relates.
Functions reference
29-13
Plan Chart Manager
PcmMenuName(50)
(string)
PcmMenuSensitive
(long)
PcmMenuChecked
(long)
The description of the menu item.
This indicates whether the menu item is currently enabled or disabled. The possible values are: true The menu item is enabled.
false The menu item is disabled and cannot be selected.
This specifies whether or not a tick is placed beside the menu item to indicate its ’selected’ status. The possible values are: true A tick is placed beside the menu item.
false No tick is placed beside the menu item, or an existing tick is removed.
Overview
On the planning board you can create buttons to which you can link sessions or options. You must create a PCM_OT_BUTTON object for each button.
Attributes
PcmButtonId
(long)
PcmButtonName(50)
(string)
PcmButtonSensitive
(long)
The unique identification number of the button. This is included in PCM_EVTPUSSBUTTON events, in order to identify the button that the user selected.
The text string for the button’s label.
This indicates whether the button is currently enabled or disabled. The possible values are: true The button is enabled.
false The button is disabled and cannot be selected.
Functions reference
29-14
Plan Chart Manager
Overview
A plan chart represents a projection of activities on a time scale. An efficient time scale is essential in order to make the chart as clear as possible. To divide the time scale, you require a base unit. In the Plan Chart Manager, any time unit, from seconds to years, can be used as the base unit. In practice, the base unit is usually one day.
You can define several time scales for each plan chart. You must create a
PCM_OT_TIMESCALE object for each of the time scales included in the chart.
You specify start and end dates for the time scale with the function pcm.create().
These can, for example, be specified as the number of days since 01-01-0001.
The following predefined variables are available for PCM_OT_TIMESCALE objects.
PCM_DAYNO
PCM_WEEKDAYNO
PCM_WEEKNO
The number of days since 01-01-0001.
The day number in the week (1 to 7).
The week number in the year (0 to 53).
PCM_MONTHDAYNO The day number in the month (1 to 31).
PCM_MONTHNO The month number in the year (1 to 12).
PCM_YEARNO The day number in the year (1 to 366).
Attributes
PcmTimescaleVisible
(long)
PcmTimescaleDesc
(string)
PcmTimescaleExprV
(string)
PcmTimescaleExprD
(string)
PcmTimescaleInterval
(double)
This flag indicates if the time scale must be visible on the planning board. Possible values are true and false.
The format of the description on the time scale – for example, month numbers, day numbers, and so on.
See sprintf$().
This expression determines how the time scale must be divided and where the ticks indicating the divisions must be placed.
This expression determines the value by which the substitution symbol specified in PcmTimescaleDesc must be replaced – for example, a day number.
The interval for the time scale division.
Functions reference
29-15
Plan Chart Manager
Example
Base Unit: Day
Time Scale Division: Week Numbers pcm.create.object ( plan_id, PCM_OT_TIMESCALE,
PcmTimescaleVisible, TRUE,
PcmTimescaleDesc, "Week %D(%w)",
PcmTimescaleExprV, "PCM_WEEKDAYNO = 1",
PcmTimescaleExprD, "PCM_DAYNO",
PcmTimescaleInterval, 1 )
In this example, the starting point of the time scale is a number representing the number of days since 01-01-0001. At each division, the Plan Chart Manager increments this value (ExprD) by 1 (Interval) and checks if this day coincides with the start date of a week (ExprV). If the latter expression is true, a mark is placed on the time scale containing a week number. In fact, if ExprV is true, the following statement is executed: sprintf$(PcmTimescaleDesc, PcmTimescaleExprD) that is, sprintf$("Week %D(%wer)", PCM_DAYNO)
Overview
Delay time is a span of time characterized as non-working time – for example, weekends and holidays. It can be indicated in a chart by hatched lines. You must create a PCM_OT_DELAY object for each delay time period you want to include in the chart. The same delay time object can be repeated at regular intervals – to indicate weekends, for example.
Attributes
PcmDelayStart
(double)
PcmDelayFinish
(double)
The starting point of the delay time on the time scale.
The end point of the delay time on the time scale.
Functions reference
29-16
Plan Chart Manager
PcmDelayRepeat
(long)
PcmDelayInterval
(double)
This indicates whether or not the delay time is repeated.
The possible values are: true delay time is repeated false delay time occurs only once
If PcmDelayRepeat = true, use this flag to specify the interval at which the delay time must be repeated. The format depends on the division of the time scale.
Overview
You can define up to nine columns for each chart plan. These columns contain the activity descriptions. The first column you define becomes the leftmost column on the planning board. You must create a PCM_OT_COLUMN object for each column you want to include in the chart.
Attributes
PcmColumnVisible
(long)
PcmColumnName
(string)
PcmColumnWidth
(double)
PcmColumnIndent
(long)
This indicates whether or not the column is to be visible in the chart plan. The possible values are true and false.
The title of the column. This is placed over the column.
The column width, expressed in characters (up to 50).
This indicates whether or not the texts relating to subactivities are indented. The possible values are: true texts relating to subactivities are indented false all texts start at the left margin of the column
Functions reference
29-17
Plan Chart Manager
Overview
An activity is an event or series of events with a start and end time. There are parent activities and subactivities. A parent activity can be an independent activity within a project or it can have one or more subactivities. Subactivities are always linked to a parent activity. Activities can be repeated in the plan chart.
n n n
An activity consists of the following parts: n
Part reported completed
Part still to be executed
Lower margin – that is, the number of time units the activity may start earlier that the defined start time
Upper margin – that is, the number of time units by which the end time of the activity may be exceeded
You must create a PCM_OT_ACTIVITY object for each activity you want to include in the chart.
Attributes
PcmActivityParent
(long)
PcmActivityBrother
(long)
PcmActivityGroup
(long)
The object ID of the activity's parent activity. The parent ID of a parent activity is 0.
An activity can occur several times in one project
(repeated activity). The activity is placed several times on the same line, each time shifted in time. In this flag, specify the object ID of the activity that is to be repeated.
By grouping activities, you can assign different colors to different groups of activities. You can define up to nine activity groups. Use this attribute to specify the group number for the activity.
The starting point of the activity on the time scale.
PcmActivityStart
(double)
PcmActivityFinish
(double)
PcmActivityProgress
(double)
The end point of the activity on the time scale.
The part of the activity reported completed (as a percentage).
Functions reference
29-18
Plan Chart Manager
PcmActivityFreeStart
(double)
PcmActivityFreeFinish
(double)
PcmActivityTotalStart
(double)
PcmActivityTotalFinish
(double)
PcmActivityText1
PcmActivityText9
(string)
PcmActivitySort
(string)
PcmActivityCritical
(long)
The starting point of the free float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityStart. The free float is the degree to which an activity can be moved in time without influencing the start or end time of other activities.
The end point of the free float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityFinish.
The starting point of the total float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityStart. The total float is the degree to which an activity may be moved in time without influencing the start or end time of the entire project.
The end point of the total float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityFinish.
An explanatory text for the activity. This is displayed in the specified column. You can create as many texts (per activity) as there are columns. See also PCM_OT_COLUMN.
Activities can be sorted (for example, by start time).
Use this to specify the string by which they must be sorted.
This flag indicates if the activity is part of the critical path. The critical path is the longest route between the start and end of the project. Any change in one of the activities or relations that are part of the critical path directly influences the project’s end time. The possible values are: true the activity is part of the critical path false the activity is not part of the critical path
Functions reference
29-19
Plan Chart Manager
PcmActivityExpand
(long)
PcmActivityEdit
(long)
This flag determines if subactivities are shown on the plan chart. The possible values are:
PCM_EM_EXPAND
Show subactivities.
PCM_EM_NOEXPAND
Do not show subactivities.
PCM_EM_TOGGLE
Toggle between EXPAND and EXPAND.
This flag determines whether or not users are authorized to modify or move the activity. The possible values are:
PCM_ED_NOEDIT
The user is not authorized to change or shift the activity in time.
PCM_ED_START
The user is authorized to shift the entire activity in time. This is done by dragging the start point of the activity with the mouse.
PCM_ED_FINISH
The user is authorized to shorten or lengthen the activity. This is done by dragging the end point of the activity with the mouse.
You can combine PCM_ED_START +
PCM_ED_FINISH in order to authorize users to both shift and change activities.
Overview
On the planning board you can record relations between different activities and/or markers. These relations define the mutual relationships between such objects. You can record, for instance, that certain activities must be completed before another activity can start. Also, two related activities can be separated by a mandatory interval (for example, if a coat of paint must dry for two days before the next activity can take place) or they can overlap.
Functions reference
29-20
Plan Chart Manager
You must create a PCM_OT_RELATION object for each relation you want to include in the chart.
The Plan Chart manager supports the following relation types: start-start Activity 1 can start as soon as activity 2 has started.
start-end end-start end-end
Activity 1 can start only when activity 2 is completed.
Activity 2 can start when activity 1 is completed.
Activity 2 can end only when activity 1 is completed.
Attributes
PcmRelationObject1
(long)
PcmRelationObject2
(long)
PcmRelationGroup
(long)
This specifies the object ID of object 1.
This specifies the object ID of object 2.
PcmRelationType
(long)
PcmRelationDelay
(double)
PcmRelationCritical
(long)
By grouping relations, you can assign different colors to different groups of relations. You can define up to nine relation groups. Use this attribute to specify the group number for this relation.
The relation type. The possible values are:
PCM_RT_STARTSTART
PCM_RT_STARTEND
PCM_RT_ENDSTART
PCM_RT_ENDEND
The time span between the two related activities.
This number is placed alongside the line that indicates the relationship (this can also be a negative value).
This flag indicates if the relation is part of the critical path. The critical path is the longest route between the start and end of the project. Any change in one of the activities or relations that are part of the critical path directly influences the project’s end time. The possible values are: true the activity is part of the critical path false the activity is not part of the critical path
Functions reference
29-21
Plan Chart Manager
Overview
You can place markers on the planning board to indicate when certain standard actions must take place – for example, "Principal's Approval". Markers are defined at a specific point in time. You must create a PCM_OT_MARKER object for each marker you want to include in the chart.
Attributes
PcmMarkerActivity
(long)
PcmMarkerType
(long)
The object ID of the activity that must be marked.
The marker type. The possible values are:
PCM_MT_RECTANGLE
PCM_MT_TRIANGLE
PCM_MT_DIAMOND
PCM_MT_STAR
PCM_MT_ARROW
The time where the marker is to be placed.
PcmMarkerStart
(double)
PcmMarkerText
(string)
PcmMarkerEdit
(long)
A text explaining the marker.
PcmMarkerGroup
(long)
This flag determines whether or not users can move the marker. The possible values are:
PCM_ED_NOEDIT
The user is not authorized to shift this marker in time.
PCM_ED_START
The user is authorized to shift this marker in time. This is done by dragging the starting point with the mouse.
By grouping markers, you can assign different colors to different groups of markers. You can define up to three marker groups. Use this attribute to specify the group number for this marker.
Functions reference
29-22
Plan Chart Manager
#include <bic_pcm>
#define MI_MENU1 100
#define MI_MENU2 101
#define MI_BUTTON1 200 long plan_id long time_start long time_finish long actv1 function main()
{
| check if display server supports graphics if is.graphical.server() then start.planboard() | start pcm server;
| create objects handle.event.loop() | handle pcm events endif
} function long is.graphical.server()
{ long srv_type, srv_data(SRVMAXSIZE)
} srv_type = get.display.data(srv_data) return( srv_type = DSBW ) function handle.event.loop()
{ string data list(256) long event(EVTMAXSIZE) while next.event(event) on case evt.type(event) case EVTBUCKETMESSAGE: data list = bms.receive$() on case evt.bms.sender(event) case plan_id: on case evt.bms.command(event) case PCM_EVTMENUSELECT: handle.evtmenuselect(data list) break case PCM_EVTPUSHBUTTON: handle.evtpushbutton(data list)
Functions reference
29-23
Plan Chart Manager
break case PCM_EVTOBJECTPRESS: handle.evtobjectpress(data list) break case PCM_EVTOBJECTDPRESS: handle.evtobjectdpress(data list) break case PCM_EVTOBJECTMOVE: handle.evtobjectmove(data list) break case PCM_EVTCLOSED: handle.evtclosed() break endcase break endcase break endcase endwhile
} function handle.evtmenuselect( ref string data list() )
{ long menu_id | selected menu long object_type | type of selected object long object_id | selected object
} pcm.get.data( PCM_EVTMENUSELECT, data list, menu_id, object_type, object_id ) on case menu_id case MI_MENU1:
....
break
.
.
endcase function handle.evtobjectdpress( ref string data list() )
{ long object_type | type of selected object long object_id | selected object double time | time of selected object pcm.get.data( PCM_EVTOBJECTDPRESS, data list,
object_type, object_id, time ) on case object_type case PCM_OT_ACTIVITY: pcm.change.object( plan_id, object_id,
PcmActivityExpand, PCM_EM_TOGGLE )
Functions reference
29-24
Plan Chart Manager
} pcm.refresh(plan_id) break case PCM_OT_RELATION:
....
break case PCM_OT_MARKER:
....
break endcase function handle.evtobjectmove()
{ long object_type | type of selected object long object_id | selected object double start | new start time double finish | new finish time pcm.get.data( PCM_EVTOBJECTMOVE, data list,
object_type, object_id, start, finish ) on case object_type case PCM_OT_ACTIVITY: move.activity( object_id, start, finish ) break
.
.
endcase
} function move.activity( long actv_id, double strt, double fnsh )
{ pcm.change.object( plan_id, actv_id,
PcmActivityStart, strt,
PcmActivityFinish, fnsh,
PcmActivityFreeStart, strt - 1,
PcmActivityFreeFinish, fnsh + 2 ) pcm.refresh( plan_id )
} function handle.evtclosed()
{ close.planboard() exit(0)
} function start.planboard()
{ long par_menu, menu2, butt1
Functions reference
29-25
Plan Chart Manager
time_start = date.num() time_finish = time_start + 100 plan_id = pcm.create(PcmPlanName, "Project 1993",
PcmPlanFontHeight, 15,
PcmPlanLineHeight, 2.0,
PcmPlanBackgroundColor, RGB.WHITE,
PcmPlanForegroundColor, RGB.BLACK,
PcmPlanTimescaleStart, time_start,
PcmPlanTimescaleFinish, time_finish,
PcmPlanTimescaleWidth, 3.0,
.
.
PcmPlanMarkersVisible, TRUE )
| -- create objects par_menu = pcm.create.object( plan_id, PCM_OT_MENU,
PcmMenuParent, 0,
PcmMenuId, MI_MENU1,
PcmMenuName, "File" ) menu2 = pcm.create.object( plan_id, PCM_OT_MENU,
PcmMenuParent, par_menu,
PcmMenuId, MI_MENU2,
PcmMenuName, "open" ) butt1 = pcm.create.object( plan_id, PCM_OT_BUTTON,
PcmButtonId, MI_BUTTON1,
PcmButtonName, "Close" ) pcm.create.object( plan_id, PCM_OT_TIMESCALE,
PcmTimescaleVisible, TRUE,
PcmTimescaleDesc, "%D(%H)",
PcmTimescaleExprV,"PCM_MONTHDAYNO = 1",
PcmTimescaleExprD, "PCM_DAYNO",
PcmTimescaleInterval, 1 ) pcm.create.object( plan_id, PCM_OT_TIMESCALE,
PcmTimescaleVisible, TRUE,
PcmTimescaleDesc, "%D(%d)",
PcmTimescaleExprV, "TRUE",
PcmTimescaleExprD, "PCM_DAYNO",
PcmTimescaleInterval, 1 ) pcm.create.object( plan_id, PCM_OT_COLUMN,
PcmColumnVisible, TRUE,
PcmColumnName, "Id",
PcmColumnWidth, 10,
PcmColumnIndent, FALSE )
Functions reference
29-26
Plan Chart Manager
} actv1 = pcm.create.object( plan_id, PCM_OT_ACTIVITY,
PcmActivityParent, 0,
PcmActivityStart, time_start + 5,
PcmActivityFinish, time_start + 20,
PcmActivityProgress, 0,
PcmActivityFreeStart, time_start + 4,
PcmActivityFreeFinish, time_start + 22,
PcmActivityText1, "Activity 1",
PcmActivityCritical, TRUE,
PcmActivityExpand, PCM_EM_EXPAND,
PcmActivityEdit, PCM_ED_START + PCM_ED_FINISH ) function close.planboard()
{ pcm.destroy(plan_id)
}
Functions reference
29-27
Plan Chart Manager
Functions reference
29-28
Use these functions for handling processes.
long long act.and.sleep
( string procname(.) [, "arg1",
"arg2" ...] ) activate ( string procname(.) [, "arg1",
"arg2" ...] ) long argc string argv$
( )
( num_expr ) long void long bshell.pid
kill pstat
( )
( long processno )
( long pid, ref string progname, ref long info(PSMAXSIZE) )
( long processno ) void void reactivate signal void sleep void suspend string wait long wait.and.
activate
( long type, long action )
( long processno )
( long msec )
( ref long process_id, long option )
( string procname(.) [, "arg1",
"arg2", ...] )
See also
Chapter 31, Process groups.
Chapter 7, Multitasking and the GUI, in U7168A US BaanERP Tools:
Programming Features.
Functions reference
30-1
Processes
Syntax
long act.and.sleep( string procname(.) [, "arg1", "arg2"
...] )
Description
This activates the specified process and places it in the sleeping process queue. It remains there until it is activated by calling the reactivate() function. You can remove the process with the kill() function. The process is automatically removed when the process group to which it belongs is killed.
Arguments
procname
The process to be activated. The argument can contain a session name (4GL programs) or the name of an object file
(3GL programs).
arg1, arg2, ...
Use these optional arguments to pass arguments to the new process. The arguments are always converted to strings.
The new process can access these arguments with the argv$() function.
Return values
0
>0 process cannot be activated process ID of activated process
Context
Bshell function.
Functions reference
30-2
Processes
Syntax
long activate( string procname(.) [, "arg1", "arg2" ...] )
Description
This activates the specified process and places it in the running process queue.
Execution starts when the bshell schedules CPU time for the process.
Arguments
procname
The process to be activated. The argument can contain a session name (4GL programs) or the name of an object file
(3GL programs).
arg1, arg2, ...
Use these optional arguments to pass arguments to the new process. The arguments are always converted to strings.
The new process can access these arguments with the argv$() function.
Return values
0
>0 process cannot be activated process ID of activated process
Context
Bshell function.
Syntax
long argc()
Description
This returns the number of arguments of the current program. You can pass arguments to the program by activating it with the activate(), act.and.sleep(), or
Functions reference
30-3
Processes
Context
Bshell function.
Example
string str_arr(10, 4) | 4 strings of length 10 activate("other_program", str_arr) | argc() in other
| program has the value 5
Syntax
string argv$( num_expr )
Description
This returns the specified argument of the program as a string. The program name is stored in ARGV$(0). The last argument is stored in ARGV$(ARGC()-
1).
You can pass arguments to the program by activating it with the activate(),
as an argument, all elements of the array are passed as single arguments.
Return values
The specified argument as a string. Or an empty string () if the argument does not exist.
Context
Bshell function.
Syntax
long bshell.pid()
Description
This returns the process ID of the current bshell (at operating system level).
Functions reference
30-4
Processes
Context
Bshell function.
Syntax
void kill( long processno )
Description
This deletes the specified process from the bshell process queue. If the process is in a running state, it is interrupted.
Notes
Do not confuse this function with the kill command of the operating system. You can use kill() to kill process within the same bshell only. You cannot use it to kill the processes of other users.
If you kill a child process while the parent process is sleeping, the parent process is automatically wakened, provided that both processes are in the same process group.
Context
Bshell function.
Syntax
long pstat ( long pid, ref string progname, ref long info(PSMAXSIZE) )
Description
This returns status information about a specified process.
Functions reference
30-5
Processes
Arguments
pid
The ID of the process for which you want to retrieve information.
Specify a negative value here to retrieve information about the init process.
progname
This returns the process code.
info
This returns status information that you can retrieve with the following macros:
returns PSRUNNING, PSBLOCKING,
PSSLEEPING, or PSTERMINATING
returns the identifier of the process group to which the process belongs
process group
Return values
The process ID of the next process in the internal process list.
Context
Bshell function.
Example
long info(PSMAXSIZE) string progname(512) long procid procid = pstat( -1, progname, info ) while procid > 0
| process info procid = pstat( procid, progname, info ) endwhile
Functions reference
30-6
Processes
Syntax
void reactivate( long processno )
Description
This activates the specified sleeping process.
Syntax
void signal( long type, long action )
Description
This specifies whether the process in which it is called ignores child process signals or not.
Arguments
type
The signal type. Currently there is only one value for this argument:
SIGCHLD
Sent by a child process to its parent process when the child process exits.
action
SIGIGN
Ignore signals. The child exits without any action by the parent. The child exits, sends an exit signal to its parent, and is removed. This is the default action.
SIGNOIGN
Do not ignore signals. The child exits and waits until its parent catches its exit signal. The parent catches the signal with the wait() function.
While the child process is waiting, it is a zombie process.
Context
Bshell function.
Functions reference
30-7
Processes
Syntax
void sleep( long processno )
Description
This suspends execution of the specified process and places it in the sleeping process queue. To suspend execution of the your own process, specify the predefined variable pid in the processno argument.
Use reactivate() to activate a sleeping process. When a child process of a sleeping parent process exits, the parent process wakens automatically. When the last process is put in a sleeping state, the program automatically stops.
Note
Do not confuse this function with the UNIX sleep command. The latter suspends a process for a specified amount of time. In BaanERP scripts, you use suspend() to do this.
Context
Bshell function.
Syntax
void suspend( long msec )
Description
This stops execution of the current process for a specified number of milliseconds. You can specify any number of milliseconds in the range 0 to
2147483647 (the maximum value for a long).
Note
Do not confuse this function with the sleep() function. The latter puts another process in a sleeping state until it is reactivated with the reactivate() command.
Functions reference
30-8
Processes
Context
Bshell function.
Syntax
string wait( ref long process_id, long option )
Description
This waits for one or all child processes to exit.
Arguments
process_id
This returns the process number of the child process that exited. If no child exited, it returns 0. If there are no child processes, or if all child processes were already ended before the function was called, it returns -1.
option
This can have one of the following values:
WTHANG
If the parent process ignores child signals (see signal()), the function waits until all children have exited. The process_id argument returns the process ID of the last child process to exit.
If the parent process does not ignore child signals (see signal()), the function waits until one child exits. The process_id argument returns the process ID of that child process.
WTNOHANG
If the parent process ignores child signals (see signal()), the function does not block. If one or more child processes have previously exited and are in a zombie state, the process_id argument returns the process of the last child process that exited.
If the parent process does not ignore child signals (see signal()), the function waits until one child exits. The process_id argument returns the process ID of that child process.
Return values
The exit value (a string) of the child process identified by the process_id argument.
Functions reference
30-9
Processes
Context
Bshell function.
Syntax
long wait.and.activate( string progname(.) [, "arg1",
"arg2", ...] )
Description
This activates the specified program. The calling program is put in a waiting state. Because the calling program has not ended, it retains all its values.
In the called program, the predefined variable background is set to 1. By testing this variable, the program can check whether it is running as a foreground or background process. If required, the functioning of the program can be made dependent on this.
When the called program ends, the calling program is fetched from the waiting state and reactivated, starting from the statement immediately following the
belong to the same process group.
Arguments
procname
The process to be activated. The argument can contain a session name (4GL programs) or the name of an object file
(3GL programs).
arg1, arg2, ...
Use these optional arguments to pass arguments to the new process. The arguments are always converted to strings.
The new process can access these arguments with the argv$() function.
Return values
0
>0 process cannot be activated process ID of activated program
Context
Bshell function.
Functions reference
30-10
Use these functions to handle process groups.
A process group is a group of related, interdependent processes. One process is the group leader. Child processes are started by the leader or by one of its children. All processes belong to a process group.
Process groups have the following characteristics: n
Each process group has its own event queue. Events are sent to the process group, not to individual processes.
n
When one process within a group starts another process, that process is automatically placed in the same process group.
n
For the group leader, the predefined variable background is set to zero, For child processes, this variable is set to 1.
n
When a process is killed or ended, its parent is automatically awakened, unless the parent and child are in different groups.
n
You use the grab.mwindow() function to set the process group to which a main window sends its events. After calling this function, all events that occur in the main window are sent to the process group.
See Chapter 30, Processes, for details of the functions available for handling processes.
long void void long get.pgrp
grab.mwindow
kill.pgrp
set.pgrp
( long process_id )
( long mwindow, long process_group )
( long process_group )
( long process_id, long group_id )
Functions reference
31-1
Process groups
Syntax
long get.pgrp( long process_id )
Description
This returns the identification number of the process group to which the specified process belongs. If you specify an unknown process ID, -1 is returned.
Context
Bshell function.
Example
long group group = get.pgrp( pid )
Syntax
void grab.mwindow ( long mwindow, long process_group )
Description
This specifies the process group to which a particular main window must send its events. After calling this function, all events that occur in the main window are sent to the process group. grab.mwindow() is mainly used immediately after creation of a new process group.
Arguments
mwindow
The ID of the main window.
process_group
The ID of the process group.
Context
Bshell function.
Functions reference
31-2
Process groups
Example
long group mwindow group = set.pgrp(pid, pid) | Create a new group grab.mwindow(mwindow, group)
| Send all events to the new group
Syntax
void kill.pgrp( long process_group )
Description
This ends all processes within the specified process group. All windows and graphical parts of the processes are removed.
Context
Bshell function.
Example
long child_group, child_pid child_group = set.pgrp( child_pid, child_pid )
....
....
kill.pgrp( child_group )
Syntax
long set.pgrp( long process_id, long group_id )
Description
This places a specified process in a specified process group. If the process group
ID is the same as the process ID, a new process group is created with the specified ID. The specified process becomes the leader of the new group.
The parent of the process does not change when you call this function.
Functions reference
31-3
Process groups
Return values
The function returns the ID of the process group. If the specified group does not exist, and if the group ID is not the same as the process ID, the function returns -
1.
Context
Bshell function.
Example 1
long any_group set.pgrp(pid, pid) | creates a new process group set.pgrp(pid, any_group) | sets pid in any_group
Example 2
long mwindow, child mwindow = create.mwindow(....) change.mwindow( mwindow ) child = activate( "my.program" ) if child then set.pgrp( child, child ) grab.mwindow( mwindow, child ) endif
Functions reference
31-4
A progress indicator provides feedback to the user on the progress of a lengthy operation. It consists of a rectangular bar that fills from left to right as the operation progresses, indicating the percentage of completion of the operation. It can also (or alternatively) display a series of text messages that describe the progress of the operation.
You can create progress indicators in both UI and DAL scripts.
long long create.progress.indicator
change.progress.indicator
( string title() [, long mode] )
( long percentage [, string message, ...]) void destroy.progress.indicator
( )
Syntax
long create.progress.indicator( string title() [, long mode] )
Description
This creates a progress indicator with the specified title displayed in its title bar.
The progress indicator is activated after the first update.
You can create only one progress indicator per session.
Functions reference
32-1
Progress indicators
Arguments
title
The title for the progress indicator window.
mode
This optional argument can specify a combination of the following values:
PROGRESS.BAR
Create a progress bar.
PROGRESS.STOP
Add a Stop button to the progress bar window. The user can click on this button to stop the operation; changes already made are not canceled.
PROGRESS.CANCEL
Add a Cancel button to the progress bar window. The user can click on this button to stop the operation; any changes already made are canceled.
PROGRESS.NOAUTODESTROY
The progress bar window is not automatically destroyed when the progress bar value changes to 100%.
Return values
0
-1 success error
Context
4GL library function.
Syntax
long change.progress.indicator( long percentage [, string message, ...] )
Description
This changes the value of the progress indicator.
Functions reference
32-2
Progress indicators
Arguments
perc
A value in the range 0 – 100. This indicates the percentage of completion of the operation.
message
This optional argument displays a string that provides information about the progress of the operation. For example, if the process involves multiple stages, you could add a short description of each stage to the progress indicator.
If you include more than one message argument, each successive message is displayed below the previous one.
Return values
0
PROGRESS.STOP
PROGRESS.CANCEL
No signal sent.
Stop button pressed. Function must stop.
Cancel button pressed. Function must stop and cancel any changes made.
Context
4GL library function.
Syntax
void destroy.progress.indicator()
Description
Destroys the progress indicator.
Context
4GL library function.
Functions reference
32-3
Progress indicators
function x()
{ create.progress.indicator( form.text$("tdsls1100.01" ),
PROGRESS.BAR + PROGRESS.STOP ) for i = 1 to n if change.progress.indicator((i*100)/n) then abort.transaction() break endif
| process element i endfor
}
Functions reference
32-4
Use these functions for generating random numbers.
long double long void void random rnd.d
rnd.i
rnd.init
srand
( )
( )
( [long range] )
( long seed )
( long seed )
Syntax
long random()
Description
This function uses a system-independent random number generator. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.
Calls to this function return successive random numbers in the range 0 to 32767.
The function uses a multiplicative congruential random number generator, with period 232. The default seed is 1. To use a different seed, call srand() before starting the generator.
Return values
A random number.
Context
Bshell function.
Functions reference
33-1
Random number generators
Example
long r_number srand( 200 ) r_number = random()
Syntax
double rnd.d()
Description
This function uses a system-independent random number generator. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.
Calls to rnd.d() return successive random numbers in the range 0.0 to 1.0. Use
you do not do this, the first result of rnd.d() is undefined.
Return values
A random number in the range 0.0 to 1.0.
Context
Bshell function.
Syntax
long rnd.i( [long range] )
Description
This function uses a system-independent random number generator. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.
Calls to rnd.i() return successive random numbers in the range 0 to 32767. You can specify a range argument if you want to limit the range further. The function then returns numbers in the range 0 to range-1.
Functions reference
33-2
Random number generators
Use rnd.init() to specify a seed value before starting the random number generator. If you do not do this, the first result of rnd.i() is undefined.
Return values
A random number in the default or specified range.
Context
Bshell function.
Syntax
void rnd.init( long seed )
Description
generate random numbers. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.
the seed argument (the seed can be any long value). If rnd.init() is not called before starting the generator, then the first results of rnd.d() and rnd.i() are undefined.
Context
Bshell function.
Syntax
void srand( long seed )
Description
number generator. The default seed is 1. srand() resets the random number generator to the starting point specified by the seed argument (the seed can be any long value).
Functions reference
33-3
Random number generators
Context
Bshell function.
Example
long r_number srand( 175 ) r_number = random()
Functions reference
33-4
Use these functions to activate reports and send data to them. Note that the rprt.* functions are short versions of the brp.* functions.
void long long void long void long void brp.close
brp.open
( long brp_id )
( string rep_name(16), string device(14), long mode ) brp.open.language
( string rep_name(16), string lang, string device(14), long mode ) brp.ready
choice.report
( long brp_id )
( ref string reportname(15) ) rprt_close rprt_open rprt_send
( [ long mess_flag ] )
( )
( )
Syntax
void brp.close( long brp_id )
Description
This stops the report writer for the specified report. brp_id is the report ID returned by brp.open() or brp.open.language() when the report was activated.
The report is sorted (if necessary) and sent to the printer spooler.
If output from different reports is sent to one spool file, you can manage the opening and closing of the printer spooler in the script by calling spool.open before calling brp.open() and by calling spool.close after closing the last report with brp.close(). By default, the spooler is opened and closed automatically.
Functions reference
34-1
Reports
Context
Bshell function.
Example
See brp_open().
Syntax
long brp.open( string rep_name(16), string device(14), long mode )
Description
This activates a specified report and opens a specified spooler device (if it is not already open). Several reports can be active simultaneously. In a 4GL script, the name of the current report is stored in the predefined variable spool.report. This variable is available in the on.choice subsection of a choice.print.data section.
Arguments
rep_name
The name of the report. Do not include a language code. The language of the user is automatically used.
device
The code of the device on which the report must be printed. This code must be defined in the data dictionary. If you specify an empty string here, you can use the mode argument to display a window in which the user can select the required device.
mode
0
1
2
User is not prompted to select a spooler device.
A window is displayed in which the user can select a spooler device. A Cancel button enables the user to cancel the operation.
A window is displayed in which the user can select a spooler device. There is no option for canceling the operation.
Return values
>0
0
-1 an ID for the activated report report could not be activated spooler could not be opened
Functions reference
34-2
Reports
Context
Bshell function.
Examples
Example 1
brp_id1 = brp.open( "rtccom040101000", "F", 0 )
| Spooler is opened automatically brp.ready( brp_id1 ) brp.close( brp_id1 )
Example 2
spool.open( "", spool.device, 1 )
| Open spooler in script brp_id1 = brp.open( "rtccom040101000", "D", 1 )
| Spooler is not opened by report writer brp_id2 = brp.open.language( "rtccom0401010003", spool.device,
1 )
| Open next report in language code 3
...
<store values> brp.ready( brp_id1 ) brp.ready( brp_id2 )
...
brp.close( brp_id1 ) brp.close( brp_id2 ) spool.close()
| Close reports
| Close spooler in script
Syntax
long brp.open.language( string rep_name(16), string lang, string device(14), long mode )
Description
This is the same as brp.open() in most respects, except that it includes a language argument. This enables you to specify a language for the report other than the default user language.
Functions reference
34-3
Reports
Return values
>0
0
-1 an ID for the activated report report could not be activated spooler could not be opened
Context
Bshell function.
Example
See brp_open().
Syntax
void brp.ready( long brp_id )
Description
This signals the report writer that a record is ready to be imported into a particular report. The report writer then prints the record. You call this function after filling the fields of a record that the report writer can process. The fields are specified in the report and must be declared as EXTERN in the program script.
Arguments
brp_id
This identifies the particular report into which the record must be imported. It is the ID returned by brp.open() or brp.open.language() when the report was activated.
Context
Bshell function.
Example
See brp_open().
Functions reference
34-4
Reports
Syntax
long choice.report( ref string reportname(15) )
Description
This returns the name of a report from the session data in the data dictionary. The report is taken from the group defined in the predefined variable reportgrp
(default = 1). If there is more than one report in the group, the user is presented with a menu from which to select the required report.
The returned name consists of 15 characters, starting with an r. The language code is not included in the name. If you call brp.open() with the report name returned by this function, the report is opened with the user language. If you call
opened with the specified language.
Notes
The standard program calls choice.report() immediately before execution of the
report group 1 is retrieved. To retrieve a report from a different group, you can assign any group to the predefined variable reportgrp in the before.choice subsection of the choice.print.data section.
Return values
>0
-1 sequence number of report in the group report not found, or no report selected by user
Context
3GL library function.
You can use this only in 4GL scripts, not in 3GL scripts.
Examples
Example 1
choice.print.data: on.choice:
| choice.report()is always called by the standard program brp_id = brp.open( reportname, "", 1 )
| report from default group 1
Functions reference
34-5
Reports
Example 2
choice.print.data: before.choice: reportgrp = 2 on.choice: brp_id = brp.open( reportname, "", 1 ) | report from
| group 2
Example 3
function choice.and.open.report()
{ if choice.report( repname ) <= 0 then return endif lfn.report = brp.open( repname, dep.device, 1 )
}
Syntax
void rprt_close( [ long mess_flag ] )
Description
This is a short version of brp.close(). It closes the report writer for the current report. You can use the function in a 4GL script in the subsection on.choice of the section choice.print.data. In this section, the predefined variable
Arguments
mess_flag
This optional argument can have one of the following values:
0
1
2
If no data is printed, the following message appears:
No data present within selection
If no data is printed, the following message appears:
No data found for report, no report is printed
If no data is printed, no message appears.
Context
3GL library function.
Functions reference
34-6
Reports
Example
See rprt_open().
Syntax
long rprt_open( )
Description
This is a short version of brp.open(). It has the same effect as: brp.open( spool.report, spool.device, 1 )
That is, it prints the current report to the default device. The predefined variables
device respectively.
Return values
>0
0
-1 an ID for the activated report report could not be activated spooler could not be opened
Context
3GL library function.
Example
if rprt_open() <= 0 then | Opens spooler and report return endif
.....
<store report values> rprt_send() rprt_close()
Functions reference
34-7
Reports
Syntax
void rprt_send( )
Description
This is a short version of brp.ready(). It has the same effect as: brp.ready( spool.report )
That is, it signals the report writer that a record is ready to be imported into the current report. The predefined variable spool.report stores the name of the current report.
Context
3GL library function.
Example
See rprt_open().
Functions reference
34-8
Resources enable users to change certain display characteristics of their user interface (colors and fonts, for example) without any programming or recompiling. See session ttdsk3160m000 (Runtime resources).
Resources are grouped into resource sets. Resource sets relate to a particular package and user combination. A resource set contains all the resources that a particular application can use. It can also be shared by different applications.
Resource sets are created and maintained using the sessions ttdsk3150m000
(Maintain resource sets) and ttdsk3155m000 (Resource set elements). The sets are stored in the data dictionary.
The resource set functions enable programs to retrieve and set individual resources in resource sets.
void void void rsc.boolean
rsc.double
rsc.enum
string rsc.font.spec
void void void rsc.get
rsc.long
rsc.put
( variable )
( variable )
( variable )
( long font_weight, long font_slant, long font_height, long font_points, long font_spacing, long font_width, long font_charwidth )
( ref string values(), string package_code(2), string resource_set(16), string resource_id(24), ... )
( variable )
( string package_code(2), string resource_set(16), string resource_id(24), string value(40) [, string resource_id(24), string value(40)] ... )
Functions reference
35-1
Resource sets
void void void void void void rsc.setboolean
( variable, string value(40) ) rsc.setdouble
( variable, string value(40) ) rsc.setenum
rsc.setlong
rsc.setstring
rsc.string
( variable, string value(40) )
( variable, string value(40) )
( variable, string value(40) )
( variable )
Syntax
void rsc.boolean( variable ) void rsc.double( variable ) void rsc.enum( variable ) void rsc.long( variable ) void rsc.string( variable )
Description
These convert a specified program variable to the corresponding resource value format (boolean, double, enum, and so on).
Context
3GL library function.
Example
See rsc.put().
Syntax
string rsc.font.spec( long font_weight, long font_slant, long font_height, long font_points, long font_spacing, long font_width, long font_charwidth )
Description
This returns a string that defines a font with the specified characteristics.
Functions reference
35-2
Resource sets
Arguments
font_weight font_slant
The font width. Possible values are: FNTMEDIUM,
FNTBOLD or FNTNORMAL.
The font slant. Possible values are: FNTROMAN or
FNTITALIC.
font_height font_points
The font height in pixels.
The font height in tenths of a point (a point is 1/72th of an inch).
font_spacing
The type of spacing. Possible values are: FNTFIXED or
FNTVARIABLE.
The average width of the font, in tenths of a pixel.
font_width font_charwidth
The average character width, in pixels. This overides the
font_width value.
Return value
A string that defines a font with the specified characteristics.
Context
3GL library function.
Example
See rsc.put().
Syntax
void rsc.get( ref string values(), string package_code(2), string resource_set(16), string resource_id(24), ... )
This retrieves one or more resource values from a specified resource set. You can use the following functions to store the resource value in a program variable:
Functions reference
35-3
Resource sets
Arguments
values
The returned resource values. This argument must be long enough to accommodate the number of requested resources.
package_code
The package code.
resource_set resource_id
The resource set ID.
One or more IDs of individual resources.
Context
3GL library function.
Example
long foreground_color, background_color string gui_font(80) domain ttdsk.rsvl resource.values(25)
| assume a defined resource set "desktop" in package "tt"
| containing resources "foreground", "background" and "font" rsc.get( resource.values, "tt", "desktop", "foreground",
"background", "font" ) rsc.setlong( foreground_color, resource_values(1,1) ) rsc.setlong( background_color, resource_values(1,2) ) rsc.setstring( gui_font, resource_values(1,3) )
| if, for example, resource_values(1,3) is empty, the
| variable gui_font is not changed.
Syntax
void rsc.put( string package_code(2), string resource_set(16), string resource_id(24), string value(40) [, string resource_id(24), string value(40)]
... )
Description
This updates one or more resource values in a specified resource set. You can use the following functions to convert program variables to a resource value format:
Functions reference
35-4
Resource sets
Arguments
package_code resource_set resource_id, value . . .
The package code.
The resource set ID.
One or more name/value pairs. Each pair consists of the ID of a resource that must be updated and the new value for that resource.
Context
3GL library function.
Example
long foreground_color, background_color string gui_font(80) foreground_color = RGB.RED
background_color = RGB.WHITE
gui_font = rsc.font.spec( FNTMEDIUM, FNTROMAN, 14, 0,
FNTVARIABLE, 140, 0 ) rsc.put( "tt", "desktop", "foreground", rsc.long( foreground_color ), "background", rsc.long( background_color ), "font", rsc.string( gui_font ) ) rsc.reload()
Syntax
void rsc.setboolean( variable, string value(40) ) void rsc.setdouble( variable, string value(40) ) void rsc.setenum( variable, string value(40) ) void rsc.setlong( variable, string value(40) ) void rsc.setstring( variable, string value(40) )
Description
These store a resource value of a particular type in a specified program variable.
Functions reference
35-5
Resource sets
Context
3GL library function.
Example
See rsc.get().
Functions reference
35-6
Use these functions to retrieve information from the runtime dictionary.
#include <bic_tt>
long long long rdi.audit.hosts
rdi.column
( string table_name(9), long comp_nr, ref string hosts())
( string column_name(18), ref string domain_name(14), ref long offset, ref long size, ref long dept, ref long type, ref long flag, ref string default_val(.) ) long string rdi.column.combined ( string column_name(18), ref string child_columns(18,32)) rdi.date.input.
format$
( string date_format(7) ) long rdi.domain
long rdi.domain.byte
( string domain_name(14), ref string oformat(.), ref string lechar(.), ref string ilchar(.), ref long adjust, ref string errmess(.), ref long range_expr_id [, ref long plen, ref string iformat(.) ] )
( string domain_name(14), ref long digits ) long rdi.domain.combined ( string domain_name(14), ref string child_domains(14,32)) rdi.domain.date
( string domain_name(14), ref long digits )
Functions reference
36-1
Runtime dictionary information
long long long long long long long long long long long long long rdi.domain.double
rdi.domain.enum
rdi.domain.enum.
value rdi.domain.float
( string domain_name(14), ref long digits_before, ref long digits_after, ref long divide_fact, ref long round_code )
( string domain_name(14), ref long no_enum_items )
( string domain_name(14), long enum_item, string language, ref string keyword(.), ref string descr(.), ref long value )
( string domain_name(14), ref long digits_before, ref long digits_after, ref long divide_fact, ref long round_code ) rdi.domain.integer
( string domain_name(14), ref long digits) rdi.domain.long
( string domain_name(14), ref long digits ) rdi.domain.set
rdi.domain.set.
value rdi.domain.string
( string domain_name(14), ref long no_enum_items )
( string domain_name(14), long enum_item, string language, ref string keyword(.), ref string descr(.), ref long value )
( string domain_name(14), ref long length, ref long convert
) rdi.domain.text
( string domain_name(14), ref long digits )
( ) rdi.first.day.of.
week rdi.index
rdi.reference
( string table_name(9), long index_no, ref long parts(32,3), ref long duplicate, ref long active )
( string column_name(18), ref string ref_column(18), ref long ref_mode, ref string ref_mess() [, long ignore_by_db] )
Functions reference
36-2
Runtime dictionary information
void long long long long long long long long long void void long long rdi.table
rdi.table.column
tt.bobject.desc
tt.chm.appl.desc
tt.chm.application
( string appl(40) ) tt.chm.chart
( string appl(40), string chart_name(16) ) tt.chm.charttype
( string appl(40), string chart_type(16) ) tt.company
tt.currency
tt.device
( long company, ref string comp_desc() mb, ref string deflt_curr(), ref long first_weekday )
( string cur(3), ref string cur_desc() mb, ref string thous_sign, ref string dec_sign, ref string symbol()
)
( string device(9), ref string desc() mb, ref long device type ) tt.field.desc
( string table_name(9), ref long no_keys, ref long no_columns, ref long int_length, ref long real_length )
( string table_name(9), long column_number, ref string column_name(18), ref string domain_name(14), ref long offset, ref long size, ref long dept, ref long type, ref long flag, ref string default_val(.))
( string b_object(10), ref string desc() mb )
( string appl(40), ref string desc() mb ) tt.index.desc
tt.language
tt.library
( string field(17), ref string desc() )
( string tabl(8), long indexnr, ref string desc())
( string lang, ref string desc(), ref string dec_sign, ref string thous_sign, ref string date_sep, ref string time_sep )
( string library.code(14), ref string library.desc())
Functions reference
36-3
Runtime dictionary information
void long void long void long long void void long tt.menu.desc
tt.menu.present
tt.report.desc
( string menu(13), string par_menu, ref string desc()mb)
( string menu(13), string par_menu )
( string reprt(15), ref string desc() ) tt.reportgroup.exis
ts tt.session.desc
( string session(13), long report_group )
( string session(13), ref string desc() ) tt.session.permissi
on
( string user(12), string session(13), ref long start_time, ref long end_time ) tt.session.present
( string session(13) ) tt.short.field.desc ( string field(17), long length, ref string desc()) tt.table.desc
( string table(8), ref string desc() ) tt.user
( string user(12), ref string name() )
Syntax
long rdi.audit.hosts( string table_name(9), long comp_nr, ref string hosts() )
Description
This returns the names of the hosts on which audit information for a particular table is stored.
Arguments
table_name
The name of the table.
comp_nr
The company number of the table.
Functions reference
36-4
Runtime dictionary information
hosts
This returns a string containing the names of all hosts on which audit information for the specified table is stored. The host names are separated by commas [,]. The local host is referred to as ’localhost’.
Return values
0
-1 success error
Context
Bshell function.
Example
Suppose that the table ttadv100, within company 100, is mirrored on the local system and on a remote system (host_99) and that the table is audited on both systems: long ret string hosts(20) ret = rdi.audit.hosts("ttadv100", 100, hosts)
| after this function call, the ’hosts’ argument contains:
| "localhost, host_99" or "host_99, localhost"
Syntax
long rdi.column( string column_name(18), ref string domain_name(14), ref long offset, ref long size, ref long dept, ref long type, ref long flag, ref string default_val(.) )
Description
This returns information about a specified table column.
Arguments
column_name
The name of the column about which you want to retrieve information.
Functions reference
36-5
Runtime dictionary information
domain_name
This returns the name of the column’s domain.
offset This returns the position of the column in the row.
size dept type
This returns the size of the column, in bytes.
This returns the depth of the column (array columns only).
This returns the database type of the column. For example,
DB.LONG, DB.FLOAT, and so on. For a list of all possible database types, see Chapter 5, Database handling, in U7168A
US BaanERP Tools: Programming Features
flag This returns a bit pattern that represents one or more of the following values:
DB.ARRAY
DB.FILLED
DB.CHILD
default_value This returns the default value of the column.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.column.combined( string column_name(18), ref string child_columns(18,32) )
Description
This returns information about the child columns of a specified column.
Arguments
column_name
The name of the column for which you wish to retrieve information.
Functions reference
36-6
Runtime dictionary information
child_colums
This returns an array containing the names of the child columns of the specified column. It can contain the names of up to 32 child columns.
Return values
The function returns the number of filled children.
Context
Bshell function.
Syntax
string rdi.date.input.format$( string date_format(7) )
Description
This returns the input format defined in the data dictionary for a specified date format. The input format can be any combination of day-in-week (D), week-inyear (W), and year (Y), or any combination of day-in-month (D), month-in-year
(M), and year (Y). For example, if the function returns MDY, the input format on a form field must be month, day-in-month, and year (for example, 12311998).
Arguments
date_format
A date format defined in the data dictionary. This must be specified as
%Dn[,lang]
, where n is the date format code and lang is the language code. See sprintf$().
Return values
The input format defined in the data dictionary for the specified date format.
Context
Bshell function.
Example
string inpformat(3) inpformat = rdi.date.input.format$( "D002,3" )
| inpformat e.g. now contains DWY.
Functions reference
36-7
Runtime dictionary information
Syntax
long rdi.domain( string domain_name(14), ref string oformat(.), ref string lechar(.), ref string ilchar(.), ref long adjust, ref string errmess(.), ref long range_expr_id [, ref long plen, ref string iformat(.) ] )
Description
This returns information about a specified domain.
Arguments
domain_name
The name of the domain for which you want to retrieve information.
oformat lechar
This returns the output format of the domain.
This returns the legal characters for the domain.
ilchar adjust
This returns the illegal characters for the domain.
This returns the domain’s alignment mode. Possible values are:
RDI.NONE
RDI.LEFT
RDI.RIGHT RDI.CENTER
errmess
This returns the domain’s error message.
range_expr_id
This returns the ID of the compiled expression for the range check.
plen iformat
This returns the maximum field length used on forms and reports.
This returns the domain’s internal format.
Functions reference
36-8
Runtime dictionary information
Return values
The function returns the domain type, or -1 if an errors occurs. The possible domain types are:
DB.BYTE
DB.INTEGER
DB.LONG
DB.FLOAT
DB.DOUBLE
DB.STRING
DB.DATE
DB.TEXT
DB.ENUM
DB.BITSET
DB.COMBINED
DB.MULTIBYTE
Context
Bshell function.
Syntax
long rdi.domain.byte( string domain_name(14), ref long digits )
Description
This returns information about a domain of type DB.BYTE.
Arguments
domain_name
The name of the domain.
digits
This returns the number of digits defined for the byte-type domain.
Return values
0
-1 success error
Context
Bshell function.
Functions reference
36-9
Runtime dictionary information
Syntax
long rdi.domain.combined( string domain_name(14), ref string child_domains(14,32) )
Description
This returns information about a domain of type DB.COMBINED.
Arguments
domain_name
The name of the domain.
child_domains
This returns an array containing the names of the children of the specified domain. It can contain the names of up to 32 children.
Return values
The number of filled children.
Context
Bshell function.
Syntax
long rdi.domain.date( string domain_name(14), ref long digits )
Description
This returns information about a domain of type DB.DATE.
Arguments
domain_name
The name of the domain.
digits
This returns the number of digits defined for the date-type domain.
Functions reference
36-10
Runtime dictionary information
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.double( string domain_name(14), ref long digits_before, ref long digits_after, ref long divide_fact, ref long round_code )
Description
This returns information about a domain of type DB.DOUBLE.
Arguments
domain_name
The name of the domain.
digits.before
This returns the number of digits before the decimal point in the specified domain.
digits_after
This returns the number of digits after the decimal point.
divide_factor
This returns the divide factor for the specified domain.
round_code
This returns the rounding mode for the specified domain.
Possible values are:
0
1
2 truncate (for example, both 1.5 and 1.49 are rounded down to 1) normal round (for example, 1.5 is rounded up to 2;
1.49 is rounded down to 1) round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values
0
-1 success error
Functions reference
36-11
Runtime dictionary information
Context
Bshell function.
Syntax
long rdi.domain.enum( string domain_name(14), ref long no_enum_items )
Description
This returns information about a domain of type DB.ENUM.
Arguments
domain_name
The name of the domain.
no_enum_items
The number of enum items in the specified domain.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.enum.value( string domain_name, long enum_item, string language, ref string keyword(.), ref string descr(.), ref long value )
Description
This returns information about a specified item in an enumerated domain.
Functions reference
36-12
Runtime dictionary information
Arguments
domain_name
The name of the domain.
enum_item
The numeric code of the enum item for which you want to retrieve information.
language keyword descr value
The language code for the enumerated domain.
This returns the name of the specified enum item.
This returns the description of the specified enum item.
This returns the value of the specified enum item.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.float( string domain_name(14), ref long digits_before, ref long digits_after, ref long divide_fact, ref long round_code )
Description
This returns information about a domain of type DB.FLOAT.
Arguments
domain_name
The name of the domain.
digits.before
This returns the number of digits before the decimal point in the specified domain.
digits_after
This returns the number of digits after the decimal point.
divide_factor
This returns the divide factor for the specified domain.
Functions reference
36-13
Runtime dictionary information
round_code
This returns the rounding mode for the specified domain.
Possible values are:
0
1
2 truncate (for example, both 1.5 and 1.49 are rounded down to 1) normal round (for example, 1.5 is rounded up to 2; 1.49
is rounded down to 1) round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.integer( string domain_name(14), ref long digits )
Description
This returns information about a domain of type DB.INTEGER.
Arguments
domain_name
The name of the domain.
digits
This returns the number of digits defined for the integer-type domain.
Return values
0
-1 success error
Context
Bshell function.
Functions reference
36-14
Runtime dictionary information
Syntax
long rdi.domain.long( string domain_name(14), ref long digits )
Description
This returns information about a domain of type DB.LONG.
Arguments
domain_name
The name of the domain.
digits
This returns the number of digits defined for the long-type domain.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.set( string domain_name(14), ref long no_enum_items )
Description
This returns information about a domain of type DB.BITSET.
Arguments
domain_name
The name of the domain.
no_enum_items
The number of set items in the specified domain.
Functions reference
36-15
Runtime dictionary information
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.set.value( string domain_name(14), long enum_item, string language, ref string keyword(.), ref string descr(.), ref long value )
Description
This returns information about a specified item in a set-type domain.
Arguments
domain_name
The name of the domain.
enum_item
The numeric code of the set item for which you want to retrieve information.
language keyword descr
The language code for the set domain.
This returns the name of the specified set item.
This returns the description of the specified set item.
value
This returns the value of the specified set item.
Return values
0
-1 success error
Context
Bshell function.
Functions reference
36-16
Runtime dictionary information
Syntax
long rdi.domain.string( string domain_name(14), ref long length, ref long convert )
Description
This returns information about a domain of type DB.STRING.
Arguments
domain_name
The name of the domain.
length
This returns the current length of the string.
convert
This returns the conversion mode of the domain. Possible values are:
RDI.UPPER
RDI.LOWER
RDI.NONE
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.domain.text( string domain_name(14), ref long digits )
Description
This returns information about a domain of type DB.TEXT.
Functions reference
36-17
Runtime dictionary information
Arguments
domain_name
The name of the domain.
digts
This returns the number of digits defined for the text-type domain.
Return values
0
-1 success error
Context
Bshell function.
Syntax
long rdi.first.day.of.week( )
Description
This function returns the first day of the week defined in the user file in the data dictionary. The returned number is relative to Sunday (=1). So, for example, if the function returns 2, this indicates that Monday is the user’s first day of the week.
Return values
The user’s first day of the week.
Context
Bshell function.
Functions reference
36-18
Runtime dictionary information
Syntax
long rdi.index( string table_name(9), long index_no, ref long parts(32,3), ref long duplicate, ref long active)
Description
This returns information about a specified index.
Arguments
table_name
The name of the relevant table (omit the leading ’t’).
index_no
The index ID.
parts
This returns the start position, length, and type of the index parts
(up to a maximum of 32 parts): parts(i,1) Start position of part i in record parts(i,2) Length of part i.
parts(i,3) Type of part i. The possible values are:
DB.BYTE
DB.TIME
DB.INTEGER
DB.TEXT
DB.LONG
DB.MAIL
duplicate
active
DB.DOUBLE
DB.BITSET
DB.STRING
DB.COMBINED
DB.DATE
DB.MULTIBYTE
Indicates whether or not duplicate values are permitted. Possible values are:
TRUE
FALSE duplicates permitted duplicates not permitted
Indicates whether or not the index is active. Possible values are:
TRUE
FALSE index is active index is not active
Return values
The number of filled parts.
Functions reference
36-19
Runtime dictionary information
Context
Bshell function.
Syntax
long rdi.reference( string column_name(18), ref string ref_column(18), ref long ref_mode, ref string ref_mess() [, long ignore_by_db] )
Description
If a database column references a column in another table, use this function to retrieve information about the referenced column.
Arguments
column_name
The name of the column which references the column about which you want to retrieve information.
ref_column
This returns the name of the column to which the column specified in column_name refers.
ref_mode
This returns the relation type. Possible values are:
1
2
3 compulsory compulsory unless empty not compulsory
ref_mess
This returns the error message of the referenced column.
ignore_by_db
This indicates whether or not a referential integrity check is performed by the database driver. Possible values are:
1
0 check ignored check performed by database driver
Return values
0
-1 success error
Context
Bshell function.
Functions reference
36-20
Runtime dictionary information
Syntax
long rdi.table( string table_name(9), ref long no_keys, ref long no_columns, ref long int_length, ref long real_length )
Description
This returns information about a specified table.
Arguments
table_name no_keys
The table name (omit the leading ’t’).
This returns the number of indices that have been created on the table.
no_columns
This returns the number of columns that are in the table, including the following columns:
Refcntd
Refcntu
_compnr
_dlock
_index<number> (a column for each index)
int_length
This returns the length of the internal buffer.
real_length
This returns the length of a row in the table.
Return values
0
-1 success error
Context
Bshell function.
Functions reference
36-21
Runtime dictionary information
Syntax
long RDI.TABLE.COLUMN( string table_name(9), long column_number, ref string column_name(18), ref string domain_name(14), ref long offset, ref long size, ref long dept, ref long type, ref long flag, ref string default_val(.) )
Description
This returns information about a specified column which is identified by the table name and the column number. Note that the first columns in the table are reserved for the following columns: Refcntd, Refcntu, _compnr, _dlock, and
_index<number> (one column for each index).
Arguments
table_name
The name of the table in which the column occurs (omit the leading ’t’).
column_number
The column number.
domain_name
This returns the name of the column’s domain.
offset size
This returns the position of the column in the row.
This returns the size of the column, in bytes.
dept type flag default_value
This returns the depth of the column (array columns only).
This returns the database type of the column. For example,
DB.LONG, DB.FLOAT, and so on. For a list of all possible database types, see Chapter 5, Database handling, in
U7168A US BaanERP Tools: Programming Features.
This returns a bit pattern that represents one or more of the following values:
DB.ARRAY
DB.FILLED
DB.CHILD
This returns the default value of the column.
Functions reference
36-22
Runtime dictionary information
Return values
0
-1 success error
Context
Bshell function.
Syntax
void tt.bobject.desc( string b_object(10), ref string desc() mb)
Description
This retrieves the description of a specified business object (b_object) and stores it in the desc argument.
Context
3GL library function.
Syntax
long tt.chm.appl.desc( string appl(40), ref string desc() mb )
Description
This retrieves the description of a specified Chart Manager application.
Arguments
appl
The name of the Chart Manager application. This takes the form:
ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager Application Data session (ttchm110m000).
Functions reference
36-23
Runtime dictionary information
desc
This returns the description of the specified Chart manager application.
Return values
0
1 success error; application not found
Context
3GL library function.
Syntax
long tt.chm.application( string appl(40) )
Description
This checks if the specified Chart Manager application is present in the runtime dictionary.
Arguments
appl
The name of the Chart Manager application. This takes the form:
ppmmxxxx, where pp is the package code, mmm is the module code, and
xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager Application Data session (ttchm110m000).
Return values
0
1 application not found application found
Context
3GL library function.
Functions reference
36-24
Runtime dictionary information
Syntax
long tt.chm.chart( string appl(40), string chart_name(16) )
Description
This checks if the specified chart is present in the specified Chart Manager application.
Arguments
appl
The name of the Chart Manager application. This takes the form: ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the
Maintain Chart Manager Application Data session
(ttchm110m000).
chart_name
The name of the chart.
Return values
0
1 success error; chart or application not found
Context
3GL library function.
Syntax
long tt.chm.charttype( string appl(40), string chart_type(16))
Description
This checks if the specified chart type is present in the specified Chart Manager application.
Functions reference
36-25
Runtime dictionary information
Arguments
appl
The name of the Chart Manager application. This takes the form:
ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager
Application Data session (ttchm110m000).
chart_type
The chart type.
Return values
0
1 success error; chart type or application not found
Context
3GL library function.
Syntax
long tt.company( long company, ref string comp_desc() mb, ref string deflt_curr(), ref long first_weekday )
Description
This returns information about a specified company.
Arguments
company comp_desc
The company number.
This returns the company description.
deflt_curr
This returns a string containing the default currency of the company.
first_weekday
This returns the first day of the week defined for the company in the data dictionary.
Return values
0
1 error; company not found success
Functions reference
36-26
Runtime dictionary information
Context
3GL library function.
Syntax
long tt.currency( string cur(3), ref string cur_desc() mb, ref string thous_sign, ref string dec_sign, ref string symbol() )
Description
This returns information about a specified currency.
Arguments
cur cur_desc
The currency code.
This returns the currency description.
thous_sign
This returns the thousands sign for the specified currency.
dec_sign
This returns the decimal sign for the specified currency.
symbol
This returns the currency symbol.
Return values
0
1 error; currency not found success
Context
3GL library function.
Functions reference
36-27
Runtime dictionary information
Syntax
long tt.device( string device(9), ref string desc() mb, ref long device_type )
Description
This returns information about a specified device.
Arguments
device desc
The device name.
This returns the device description.
device_type
This indicates the device type. Possible values are:
1
2
3
4 physical printer logical printer append to file rewrite file
5 auxiliary port
6 direct
7 display
9 Mail API
Return values
0
1 error; device not found success
Context
3GL library function.
Functions reference
36-28
Runtime dictionary information
Syntax
void tt.field.desc( string field(17), ref string desc() )
Description
This retrieves information about a specified table field.
Arguments
field
The field name.
desc
This returns the field description.
Context
3GL library function.
Syntax
void tt.index.desc( string tabl(8), long indexnr, ref string desc() )
Description
This returns information about a specified table index.
Arguments
tabl
The table name.
indexnr
The index number.
desc
This returns the description of the specified index.
Context
3GL library function.
Functions reference
36-29
Runtime dictionary information
Syntax
long tt.language( string lang, ref string desc(), ref string dec_sign, ref string thous_sign, ref string date_sep, ref string time_sep )
Description
This returns information about a specified language.
Arguments
lang desc
The language for which you want to retrieve information.
This returns the language description.
dec_sign
This returns the decimal sign defined for the language.
thous_sign
This returns the thousands sign defined for the language.
date_sep time_sep
This returns the date separator defined for the language.
This returns the time separator defined for the language.
Return values
0
1 error; language not found success
Context
3GL library function.
Syntax
long tt.library( string library.code, ref string library.desc()) )
Description
This returns information about a specified library.
Functions reference
36-30
Runtime dictionary information
Arguments
library.code
The library code.
library.desc
This returns the library description.
Return values
0
1 error; library not found success
Context
3GL library function.
Syntax
void tt.menu.desc( string menu(13), string par_menu, ref string desc() mb )
Description
This returns information about a specified menu.
Arguments
menu
The menu name.
par_menu
In the case of parallel menus, specify the menu sequence number here. Otherwise, enter 1.
desc
This returns the description of the specified menu.
Context
3GL library function.
Example
tt.menu.desc( "tfgld0000m000", "1", desc )
Functions reference
36-31
Runtime dictionary information
Syntax
long tt.menu.present( string menu(13), string par_menu )
Description
This checks if the specified menu of the current package is present in the runtime dictionary.
Arguments
menu
The menu name.
par_menu
In the case of parallel menus, specify the menu sequence number here. Otherwise, enter 1.
Return values
0
1 error; menu not found success
Context
3GL library function.
Syntax
void tt.report.desc( string reprt(15), ref string desc() )
Description
This retrieves the description of a specified report (reprt) and stores it in the desc argument.
Context
3GL library function.
Functions reference
36-32
Runtime dictionary information
Syntax
long tt.reportgroup.exists( string session(13), long report_group )
Description
This checks if a specified report group (report_group) is present in the definition of the specified session (session).
When more than one report is linked to a session, the reports may be grouped.
Report groups are useful when specific reports must be used in specific situations. The current report group is defined in the predefined variable
Return values
TRUE report group exists
FALSE report group does not exist
Example
if tt.report group.exists("tccom0401m000", 2) then reportgrp = 2 | else reportgrp = 1 (default) endif
Context
3GL library function.
Syntax
void tt.session.desc( string session(13), ref string desc())
Description
This retrieves the description of a specified session (session) and stores it in the
desc argument.
Functions reference
36-33
Runtime dictionary information
Context
3GL library function.
Syntax
long tt.session.permission( string user(12), string session(13), ref long start_time, ref long end_time )
Description
This retrieves the start and end times between which a specified user has permission to use a specified session.
Return values
0
1 error; no permission or not found success
Context
3GL library function.
Syntax
long tt.session.present( string session(13) )
Description
This checks if the specified session of the current package is present in the runtime dictionary.
Return values
0
1
2 session not present session present but not in the user configuration session present and in the configuration of the user
Context
3GL library function.
Functions reference
36-34
Runtime dictionary information
Syntax
void tt.short.field.desc( string field(17), long length, ref string desc() )
Description
This returns the description of a specified table field.
Arguments
field
The field name.
length
The number of characters of the description that must be returned.
desc
This returns the field description. Only the first length characters of the description are returned.
Context
3GL library function.
Syntax
void tt.table.desc( string table(8), ref string desc() )
Description
This retrieves the description of a specified table (table) and stores it in the desc argument.
Context
3GL library function.
Functions reference
36-35
Runtime dictionary information
Syntax
long tt.user( string user(12), ref string name() )
Description
This retrieves the name of the specified user (user) and stores it in the name argument.
Return values
0
1 error; user not found success
Context
3GL library function.
Functions reference
36-36
Use these functions for searching and sorting data. Use qss.search() to search the data for a particular value. Use qss.sort() to sort the data. The data can be a string or an array of type string, long, or double.
The qss.search() function can perform either a linear or a binary search. A binary search is faster than a linear search, but the data must first be sorted by
does not often change and so does not require repeated sorting. If the data is frequently modified, use a linear search on unsorted data instead; this avoids frequent calls to qss.sort().
long qss.search
long qss.sort
( long flag, void search, ref void tbl, ref long def [, long dept] )
( ref void tbl, ref long def [, long dept] )
Syntax
long qss.search( long flag, void search, ref void tbl, ref long def [, long dept] )
Description
This searches a specified array for a particular value, which is referred to as the search key. By default, it reads the array sequentially until it finds the specified value (that is, it performs a linear search). To perform a binary search instead, you must first sort the data with qss.sort() and then call qss.search() with the
flag argument set to QSS.SRC.IS.SORTED.
Functions reference
37-1
Searching and sorting data
Arguments
flag
This specifies which array element is to be retrieved and the type of search to be performed. You can set the argument to one of the followin possible values:
QSS.FIRST Find the first record in the array; the search argument is ignored.
QSS.LAST
Find the last record in the array; the search argument is ignored.
QSS.GT
Find the first record greater than the search key.
QSS.GTEQ
Find the first record greater than or equal to the search key.
QSS.LESS
Find the first record less than the search key.
QSS.EQLE
Find the first record less than or equal to the search key.
QSS.EQUAL Find the first record equal to the search key.
QSS.NE
Find the first record not equal to the search key.
You can combine each of these options with one or more of the following options:
QSS.SRC.IS.SORTED
Specifies a binary search. The array must previously have been sorted by using qss.sort().
QSS.LOOKUP.FOR.STRUCT
When this flag is set, the function searches the array for a specified record pattern – that is, it searches for an array element that matches both the structure and value of the search key. The search argument must have the same layout and length as the elements in tbl.
When this flag is not set, the search argument is constructed as the concatenation of the key fields defined by the def argument (see
Example 2).
QSS.SRC.DUPL.ALLOWED
Specifies that the search key can occur more than once in the source array.
search
The value that you want to search for in the specified array. This is the search key.
tbl
This specifies the array that must be searched. It can be a string or an array of type string, long, or double, but it is usually an array of strings.
Functions reference
37-2
Searching and sorting data
def
This indicates how the system is to search the array and against what conditions it must test the elements of the array. The argument must be declared as follows: long def(x,4) | x is the number of search fields
You can define several search fields (1 to x). For each search field, you define the four search properties by using the following functions.
In each case, the field_number argument specifies the sequence number (1 to x) of the search field.
n void qss.start( ref long def, long field_number, long position )
This indicates the search field’s start position in the array element.
For example, this allows you to search a string array for a character combination starting at the fourth character of the array element.
n void qss.way( ref long def, long field_number, long way )
This defines the search order that must be used if the flag
QSS.SRC.IS.SORTED is set. The argument way can be set to
QSS.UP (ascending search) or QSS.DOWN (descending search).
n void qss.type( ref long def, long field_number, long type )
This specifies the search field's type – for example, DB.LONG,
DB.DOUBLE, DB.STRING, DB.DATE, and so on.
n void qss.length( ref long def, long field_number, long length )
This specifies the length of the search field. This option is valid only for strings.
If you define fewer search fields than you have declared, you must close the def argument by calling qss.start() with a start position of zero. For example, if you have declared three search fieldss, as follows: def(3,4) but then create only two search fields, you must close the definition with the following call: qss.start(def,3,0)
Functions reference
37-3
Searching and sorting data
dept
This indicates the number of array elements (starting with the first element) that must be searched if the function is not intended to search the entire array. By default, the function searches the entire array until it finds the required value.
Return values
>0
-1 index in the array where the search key was found error; search argument not found
-11 search argument must be of same type as array;
def is not of type long array or tbl not of type array
-12 search argument not correct; string not expected
-13 dept must be positive
-14 def argument not correctly declared
-15 search argument does not fit in declared array
-16 QSS.TYPE not correct
-17 tbl argument not correct
-18 no definition found in def
-21 flag LOOKUP.FOR.STRUCT is used; search argument must be a string
-22 search argument not correct; probably a size problem – size of search must match size of an element in tbl if LOOKUP.FOR.STRUCT is set or
(if LOOKUP.FOR.STRUCT is not set) must be at least the sum of lengths of the key fields (set by qss.length())
-23 search argument not correct; probably a type problem
Context
Bshell function.
Syntax
long qss.sort( ref void tbl, ref long def [, long dept] )
Description
This function performs a fast sort a specified array.
Arguments
tbl
The name of the table or array to be sorted.
Functions reference
37-4
Searching and sorting data
def
This determines how the array is to be sorted. The argument must be declared as follows: long def(x,4) | x is the number of sort fields
You can define several sort fields (1 to x). When performing a sort, the system sorts on the first sort field. Then, if there are duplicate values in the first sort field, the system sorts on the second sort field, and so on.
For each sort field, you define the four sort properties by using the following functions. In each case, the field_number argument specifies the sequence number (1 to x) of the sort field.
n void qss.start( ref long def, long field_number, long position )
This specifies the start position of the sort field in the array elements.
n void qss.way( ref long def, long field_number, long way )
This defines the sort order. The argument way can be set to QSS.UP
(ascending sort) or QSS.DOWN (descending sort).
n void qss.type( ref long def, long field_number, long type )
This specifies the sort field’s type, for example. DB.LONG,
DB.DOUBLE, DB.STRING, DB.DATE, and so on.
n void qss.length( ref long def, long search_condition, long length )
This specifies the length of the sort field. This option is valid only when sorting strings.
If you define fewer sort fields than you have declared, you must close the def argument by calling qss.start() with a start position of zero. For example, if you have declared three sort fields, as follows: def(3,4) but then create only two sort fields, you must close the definition with the following call: qss.start(def,3,0)
dept
This indicates the number of array elements to be sorted if the function is not intended to sort the entire array. By default, the function sorts the entire array.
Functions reference
37-5
Searching and sorting data
Return values
0
-1 success error
-11 def is not of type long array or tbl not of type array
-13 dept must be positive
-14 def argument not correctly declared
-16 QSS.TYPE not correct
-17 tbl argument not correct
-18 no definition found in def
Context
Bshell function.
Example 1
| You want to sort the following (string) array.
| The number is stored as a long on positions 8 to 11 by means
| of the function store.long(number, string_array(8,X)) string string_array(11,5) long sort_def(2,4), search_def(1,4), ret qss.start(sort_def, 1, 8) qss.way(sort_def, 1, QSS.UP) qss.type(sort_def, 1, DB.LONG) qss.start(sort_def, 2, 1) qss.way(sort_def, 2, QSS.DOWN) qss.type(sort_def, 2, DB.STRING) qss.length(sort_def, 2, 5)
| The function executes an ascending sort on position 8 of
| the string. The sort must be carried out as if this is
| a long value. In case of equal values, a descending sort
| is performed on the first five characters of the string.
ret = qss.sort(string_array, sort_def)
Functions reference
37-6
Searching and sorting data
| After sorting the array will look as follows:
| If you want to know in which element the character
| combination ’iiii’ is located and be sure that the argument
| to be searched is unique and cannot occur in the last two
| elements, the following search action must be started.
| It is assumed that the array is sorted.
qss.start(search_def, 1, 2) | search from position 2 qss.type(search_def, 1, DB.STRING) qss.length(search_def, 1, 4) ret = qss.search(QSS.SRC.IS.SORTED + QSS.EQUAL, "iiii", string_array, search_def, 4)
| ret will now contain the value 2
| if the search argument is not unique, the following search
| action may be started: ret = qss.search(QSS.SRC.IS.SORTED + QSS.EQUAL +
QSS.SRC.DUPL.ALLOWED, "iiii",
string_array, search_def, 4)
Example 2
string key(50) string bank(50,10) long country(2,4) | Key on country code & bank number long sort_def(1,4) long index
| 12345678901234567890123456789012345678901234567890 bank(1,1) = "10010ING Utrecht NL " bank(1,2) = "10020ABN / AMRO Amsterdam NL " bank(1,3) = "10030Rabobank Ede NL " bank(1,4) = "20020National Westminster Bank London GB " bank(1,5) = "30010Sparkasse Munchen D " bank(1,6) = "40010Credit Lyonnais Paris F " bank(1,7) = "90010Citi Bank New York USA" bank(1,8) = "90020NBD Bank Grand RapidsUSA" qss.start (country, 1, 48) qss.type (country, 1, DB.STRING) qss.length(country, 1, 3) qss.start (country, 2, 1) qss.type (country, 2, DB.STRING)
Functions reference
37-7
Searching and sorting data
qss.length(country, 2, 5)
| WITHOUT LOOKUP.FOR.STRUCT
key = "NL" index = qss.search(QSS.GTEQ, key, bank, country) while index > 0 and bank(48,index;3) = "NL "
| process struct key = bank(48,index;3) & bank(1,index;5) index = qss.search(QSS.GT, key, bank, country ) endwhile
| WITH LOOKUP.FOR.STRUCT
key = " NL " index = qss.search(QSS.LOOKUP.FOR.STRUCT+QSS.GTEQ, key, bank, country) while index > 0 and bank(48,index;3) = "NL "
| process struct index = qss.search(QSS.LOOKUP.FOR.STRUCT+QSS.GT, bank(1,index), bank, country) endwhile
| Sorting bank table on bank description qss.start (sort_def, 1, 6) qss.type (sort_def, 1, DB.STRING) qss.length(sort_def, 1, 2) index = qss.sort( bank, sort_def)
Functions reference
37-8
Use these functions to handle printer devices and printing.
void void void long spool.buf
( const string buffer(.), long length ) spool.close
( ) spool.line
( ) spool.open
( string reportname(15), string device(14), long mode )
The following predefined variables are available for use with the spooler functions: long long long long long long long long long spool.date
spool.fontnumber
spool.id
spool.left.mrg
spool.pr.copies
spool.pg.length
spool.pg.width
spool.time
spool.view.rtl
string spool.device(14)
Date to print.
Font number:
1
2
3
LARGE
SMALL
MIDDLE
Spooler ID.
Left margin.
Number of copies.
Length of page.
Width of page, including left margin.
Time to print.
Specifies whether the report is in a bidirectional language: true bidirectional language false non-bidirectional language
Name of spooler device.
Functions reference
38-1
Spooling
string spool.fileout(100) string spool.paper.type(6) string spool.pr.line(300) string spool.report(20)
Path name for spooler output file.
Type of paper.
Line to print.
Report to be printed.
See also
Chapter 34, Reports.
Syntax
void spool.buf( const string buffer(.), long length )
Description
This sends the contents of the buffer argument to the current spooler. The current spooler must be already open. The name of the current spooler is available in the predefined variable spool.id.
No new line characters or other separators are sent to the spooler. To include these, you must program them in the buffer yourself. The length argument specifies the length of the send string. If this is 0, the spooler calculates the length of the buffer at runtime.
Context
3GL library function.
Syntax
void spool.close()
Description
This closes the spooler specified by the predefined variable spool.id. By default
currently open, set spool.id to the ID of the required spooler before you call this function. After the spooler is closed, spool.id is set to zero.
Functions reference
38-2
Spooling
Context
3GL library function.
Syntax
void spool.line()
Description
This sends the contents of the predefined variable spool.pr.line and a newline character to the spooler specified by the predefined variable spool.id. By default
currently open, set spool.id to the ID of the required spooler before you call this function. After this function has been executed, spool.pr.line is cleared.
Note that this function uses the relevant spooler predefined variables.
Context
3GL library function.
Syntax
long spool.open( string reportname(15), string device(14), long mode )
Description
This opens a specified spooler device.
Functions reference
38-3
Spooling
Arguments
reportname, device
mode
If you specify a report name in the reportname argument, it is stored in the predefined variable spool.report, and the current date and time are stored in the predefined variables spool.date and spool.time. The settings for the predefined variables
taken from the default settings for the specified report.
If you specify a device name in the device argument, it is stored in the predefined variable spool.device. The settings for the predefined variables spool.paper.type, spool.left.mrg,
settings for the specified device.
If both reportname and device are specified, the defaults for the predefined variables are taken from the default settings for the specified report. The device name is stored in spool.device.
If both reportname and device are empty (""), the predefined variables retain their values from the previous spool action.
0
1
2
This determines whether or not a window is displayed where the user can change the device settings: no window displayed window displayed with a Cancel button window displayed without a Cancel button
Note
To use several spoolers simultaneously, first open all the spoolers. Then set the predefined variable spool.id to the relevant spooler ID before each spoolline() function call.
Return values
0
>0 spooler cannot be opened
ID of opened spooler – this is also available in spool.id
Context
3GL function library.
Functions reference
38-4
Example 1
long spooler spooler = spool.open("","",1) spooler = spool.open("rtccom040101000","D",0)
Example 2
long spooler1, spooler2 spooler1 = spool.open("", "", 1) spooler2 = spool.open("", "1", 0) spool.pr.line = "Hello spooler1" spool.id = spooler1 spool.line() spool.pr.line = "Hello spooler2" spool.id = spooler2 spool.line() spool.id = spooler1 spool.close() | close spooler 1 spool.id = spooler2 spool.close() | close spooler 2
Spooling
Functions reference
38-5
Spooling
Functions reference
38-6
By default, the standard program reads the entire main table when retrieving data for a particular form, even though some records and fields may not be required.
By default also, the standard program reads only those reference table fields that are included on the form, even though the UI script and/or the DAL script may require other reference table fields.
Query extensions define conditions that the standard program adds to the
SELECT, FROM, and WHERE clauses of a database query in order to filter out unwanted records and fields of the main table and in order to include in the query all reference fields required by the form, UI script, and DAL script.
In the UI script, you program query extensions to minimize the number of records and fields of the main table read by the query and to retrieve any reference tables field that are required by the UI script but are not on the form. In the DAL script, you program query extensions to retrieve reference table fields that are required by the DAL script.
When the standard program executes a database query, it automatically adds the query extensions defined in UI and DAL scripts. So, in the case of main table fields, the standard program reads only those fields and records that meet the conditions set in the query extension in the UI script. In the case of reference tables, the standard program reads those fields included on the main table and also those mentioned in the UI and DAL scripts.
n
Identify the reference table fields required for method.is.allowed().
n
Identify the reference table fields required for executing checks in property and object hooks.
Functions reference
39-1
SQL query extensions
n
Extend the DAL query in the most efficient way possible (for example, avoid using table.*
).
n
For example, define a normal query that specifies all the referenced fields/tables and then filter out unwanted fields/tables. Check the joins carefully to ensure that multiple records are not selected. Then split the query into strings appropriate for input to the query.extend.* functions.
Because the query must return the most recent values for reference table fields, you must use the buffered values for the fields. To do this, append a colon [:] to properties of the current class that are used in the
n
Normally, you specify EXTEND_OVERWRITE as the mode for the
further extend a query that has already been extended.
n
Identify the reference table fields that are used in the UI script but not included on the form.
n
Eliminate any fields that have been included in the DAL query extension of the main table.
n
Identify the conditions required for filtering the data.
n
Identify the form fields and external variables that require table values and bind the form fields to the table fields.
n
Construct the query extension in the most efficient way possible. When dealing with non-zoom sessions, program the query extension in the
query extension in the before.zoom section. Note that, for zoom sessions, you use query extensions only for filtering out unwanted data from the main table.
n
Normally, you specify EXTEND_OVERWRITE as the mode for the
extend further a query that has already been extended.
Functions reference
39-2
SQL query extensions
void clear.query.extend.in.zoom
( ) void query.extend.select
( string extension_string
[, mode] ) void query.extend.select.in.zoom
( string extension_string) void query.extend.from
( string extension_string
[, mode] )
( string extension_string) void query.extend.from.in.zoom
void query.extend.where
( string extension_string
[, mode] ) void query.extend.where.in.zoom
( string extension_string)
Syntax
void clear.query.extend.in.zoom()
Description
This clears a query extension that was previously defined in the before.zoom section of a zoom session. The standard program automatically clears the extension in the after.zoom section of the session. Use this function to force an earlier removal of the query extension. For example, to clear the query extension before defining an extension for another zoom session.
Context
4GL library function.
You can use this function only in the before.zoom section of UI scripts.
Example
See “Sample program” later in this chapter.
Functions reference
39-3
SQL query extensions
Syntax
void query.extend.select( string extension_string [, mode]) void query.extend.select.in.zoom( string extension_string )
Description
Use these to construct a query extension for the SELECT clause of a database query. Use query.extend.select() for non-zoom sessions. Use
Arguments
extension_string
A string containing the names of the fields to be included in the SELECT statement. Use commas [,] to separate the field names.
mode
This optional argument can have one of the following values:
EXTEND_OVERWRITE
Replaces any existing query extension (this is the default mode).
EXTEND_APPEND
Appends this extension to the existing extension.
Context
4GL library functions.
You can use query.extend.select() in the before.program section of UI scripts and in the before.open.object() hook of DAL scripts. You can use
Example
See “Sample program” later in this chapter.
Functions reference
39-4
SQL query extensions
Syntax
void query.extend.from( string extension_string [, mode] ) void query.extend.from.in.zoom( string extension_string )
Description
Use this to construct a query extension for the FROM clause of a database query.
Use query.extend.from() for non-zoom sessions. Use
Arguments
extension_string
A string containing the names of the fields to be included in the FROM statement. Use commas [,] to separate the field names.
mode
This optional argument can have one of the following values:
EXTEND_OVERWRITE
Replaces any existing query extension (this is the default mode).
EXTEND_APPEND
Appends this extension to the existing extension.
Context
4GL library functions.
You can use query.extend.from() in the before.program section of UI scripts and in the before.open.object() hook of DAL scripts. You can use
Example
See “Sample program” later in this chapter
Functions reference
39-5
SQL query extensions
Syntax
void query.extend.where( string extension_string [, mode] ) void query.extend.where.in.zoom( string extension_string )
Description
Use this to construct a query extension for the WHERE clause of a database query. Use query.extend.where() for non-zoom sessions. Use
Arguments
extension_string
A string containing the names of the fields to be included in the WHERE statement. Use commas [,] to separate the field names.
mode
This optional argument can have one of the following values:
EXTEND_OVERWRITE
Replaces any existing query extension (this is the default mode).
EXTEND_APPEND
Appends this extension to the existing extension.
Note
Whenever possible, use the REFERS TO construction instead of the ._INDEX1
= construction. The standard program always uses the REFERS TO construction and automatically removes all duplicates.
In BaanERP, this function replaces the predefined variable query.extension that was used in earlier versions of the software.
Context
You can use query.extend.where() in the before.program section of UI scripts and in the before.open.object() hook of DAL scripts. You can use
Functions reference
39-6
SQL query extensions
Example
See “Sample program” later in this chapter
This is an example of a simple query extension programmed in the DAL for the main table 'qmptc015'. The unit (qmptc021.cual) of the algorithm
(qmptc015.algo) must have the same physical quantity as the unit defined in the table (qmptc015.chun).
function extern long before.open.object.set()
{ query.extend.select("qmptc021.cual") query.extend.from("qmptc021") query.extend.where(":qmptc015.algo refers to qmptc021")
} function extern long qmptc015.algo.check(long has_changed)
{ if has_changed then tcibd.dll0003.read.mcs001.tccu(qmptc015.chun,
qmptc021.cual, basu.tccu, unit.tccu) if basu.tccu <> unit.tccu then dal.set.error.message("qmptcs011526")
|* Algorithm and characteristic units
|* must have the same physical quantity return(DALHOOKERROR) endif endif
}
Functions reference
39-7
SQL query extensions
Functions reference
39-8
Use these functions for starting and stopping programs and sessions
void void void abort end exit
( )
( )
( [EXITVALUE] ) long long run.baan.prog
( const string progname, const string arguments, long mode ) run.prog
( const string progname, const string arguments, long mode ) shell ( string command(.), long mode ) long string start.session
( long mode, const string session.code, const string zoomname, const string returnfld) void stop string zoom.to$
( )
( string process(14), long zoomcode, string zoomname(18), string returnfld(18), long formpos )
Syntax
void abort()
Description
This cancels execution of a program script and returns control to the application.
The database is not updated. The function has the same effect in both 3GL and
4GL scripts.
Functions reference
40-1
Starting and stopping programs and sessions
Context
Bshell function.
Syntax
void end()
Description
When used in a 3GL script, this ends the program and returns control to the application. The database is not updated.
When used in a 4GL script, the function has the same effect as the end.program standard command. When a 4GL script calls end() or execute(end.program)
, changes are stored in the database and the program ends. Before the program ends, any before.choice subsections in a
executed, if present.
Note
The functions end(), stop(), and exit() (without an exitvalue argument) in 3GL programs, and the function stop() in 4GL programs, all have the same effect.
That is, the program ends and returns control to the application. The database is not updated.
Context
3GL and 4GL library function.
Syntax
void exit( [EXITVALUE] )
Description
When included in a 3GL program that is not activated by a 4GL program, exit() has the same effect as end() and stop() in a 3GL program.
Functions reference
40-2
Starting and stopping programs and sessions
When included in a 4GL script, or in a 3GL program that is activated from a 4GL program with zoom.to$(), an exit value is returned to the calling program. The
exitvalue argument can be of any type (except an array). It is always converted to a string. If no exit value is specified, an empty string is returned.
Context
Bshell function.
Syntax
long run.baan.prog( const string progname, const string arguments, long mode ) long run.prog( const string progname, const string arguments, long mode )
Description
The function run.baan.prog() runs a BAAN program.
The function run.prog() runs an operating system command. It is a systemdependent function. It must not be used in applications that are distributed across different platforms.
Arguments
progname
The name of the program or command to be executed.
$BSE/bin/progname{release}.
If the progname argument in run.prog() does not supply the full path (absolute or relative), the system searches for the command using the standard facilities of the operating system platform (for example, under UNIX, all PATH elements are searched).
The argument can specify a remote host. For example, if
progname is tahoe!sort, the function runs the sort program on the tahoe host. The maximum number of remote programs that can run concurrently depends on available system resources.
arguments
The function start the program or command with the parameters specified here.
Functions reference
40-3
Starting and stopping programs and sessions
mode
This specifies the execution mode of the program or command.
The possible values are:
RP_WAIT
RP_NOWAIT wait for the program to finish run as a background program
Note
Output from the program cannot be displayed. If the -q switch is available, use this to output the program results to a file.
Use these functions instead of the shell() function used in previous versions of
BAAN.
Return values
0
<0
>0 program executed successfully program could not be started program did not execute successfully
Note that the return value cannot be retrieved when the mode argument is set to
RP_NOWAIT.
Context
Bshell function.
Syntax
long shell( string command(.), long mode )
Description
This starts the vt200 compatible terminal emulator to execute the command specified in the command argument. The shell (for example, UNIX, VMS, or
MPE) process is connected with the bshell by means of a pseudo tty. Running a shell does not block the bshell. You can switch to another window and perform other tasks.
Functions reference
40-4
Starting and stopping programs and sessions
Arguments
command
The command to be executed.
mode
This can be a combination of the following options:
0
No main window is created for the terminal emulator. This may result in starting a terminal emulator in the main window of the process that calls the shell function. The first status field displays
"ottstpvtemul" while the shell process is running.
SHELL_BACKGROUND
Background processing. No main window is created and the process produces no output. This is similar to
SHELL_NO_OUTPUT + SHELL_NO_WAIT.
SHELL_CLS
Current screen is cleared before the command is executed.
SHELL_CONFIRM
Displays the message "Press RETURN", or its local equivalent, in the right lower corner of the window after the shell process has finished.
SHELL_MAXWINSIZE
The terminal emulator sizes its main window to the maximum size. A new main window is created.
SHELL_NO_WAIT
The shell function does not wait for the emulator to end. This is useful for starting shell processes (such as an editor) while continuing processing. The variable shell.pid is set to the process number of the activated terminal emulator process. A new main window is created.
SHELL_NO_OUTPUT
The terminal emulator does produce any output. This implies the
SHELL_NO_MWINDOW option.
SHELL_MWINDOW
A main window is created. This displays the output of the shell command.
Functions reference
40-5
Starting and stopping programs and sessions
Notes
This function is supported for backward compatibility only. In new applications, use run.prog() and run.baan.prog() instead.
The function is available only for programs running under UNIX, and not for programs running under Windows NT.
Return values
0
-1
-2
-3
-4
-6 success maximum number of pty’s is reached; general error code cannot open the master pty pipe command failed fork of reader process or shell process failed cannot start terminal emulator
Examples
1
Run a shell command that creates no main window. Output can appear on the current main window. The bshell process waits for the shell command to end.
ret = shell("rm $BSE/tmp/file", 0)
2
Similar to example 1. The terminal emulator displays "Press <RETURN>" and waits for confirmation after the shell process has ended.
ret = shell("ls -l", SHELL_CONFIRM)
3
Run a shell command in the background. Output is displayed in a separate main window. The main window is stretched to its maximum possible size on the terminal display.
ret = shell("vi helloworld.c", SHELL_NO_WAIT +
SHELL_MAXWINSIZE)
4
Run a shell command that produces no output. Errors can be caught by checking the return value of the shell function.
ret = shell("cp /tmp/a /tmp/b", SHELL_NO_OUTPUT)
Context
Bshell function.
Functions reference
40-6
Starting and stopping programs and sessions
Syntax
string start.session( long mode, const string session.code, const string zoomname, const string returnfld )
Description
This starts a session from a program script.
Arguments
mode
Specifies the start mode for the new session. Possible values are:
MODAL
MODELESS
The parent session is blocked until the child session exits.
Parent and child are parallel sessions that can be manipulated simultaneously.
For dynamic sessions, the possible values are:
SINGLE_OCC The session is started as a single-occurrence
(details) session.
MULTI_OCC The session is started as a multioccurrence
(overview) session.
session.code
The code of the session that must be started.
zoomname
The name of the calling process. This is used in the zoom.from sections in the child session. If no name is provided here,
returnfld
Indicates the name of the variable to be returned by the function. If you specify an empty string, the function returns the exit value of the zoom process. This argument is relevant only if the start mode is MODAL.
You can also specify an index name in this variable. In this case, the values of all component fields of the index are set by the zoom session and exported back to the calling process.
Notes
You can use start.session() in both 3GL and 4GL programs, but only for starting
4GL sessions.
Functions reference
40-7
Starting and stopping programs and sessions
The function replaces other functions for starting sessions, such as zoom.to$() and start.main.session().
Return values
If you specify a variable name in the returnfld argument, the function returns the value of the specified variable. If you specify an index name in returnfld, the function returns the value of returnfld. If you specify an empty string in
returnfld, the function returns the exit value of the zoom process. If the session is canceled, the function returns an empty string.
Context
4GL library function.
Syntax
void stop()
Description
This ends the program. The program immediately exits without updating the database and without executing any further sections. The function has the same effect in both 3GL and 4GL scripts.
Note
The functions end(), stop(), and exit() (without an exitvalue argument) in 3GL programs, and the function stop() in 4GL programs, all have the same effect.
That is, the program ends and returns control to the application. The database is not updated.
Context
3GL and 4GL library function.
Functions reference
40-8
Starting and stopping programs and sessions
Syntax
string zoom.to$( string process(14), long zoomcode, string zoomname(18), string returnfld(18), long formpos )
Description
Use this to zoom to another session or menu.
Arguments
process zoomcode
Specifies the name of the session or menu that must be started.
This can be either Z.MENU or Z.SESSION, depending on whether it is a menu or session that is being started.
zoomname
The name of the calling process. This is used in the zoom.from sections in the called process. If no name is provided here,
returnfld
Indicates the name of the variable to be returned by the function.
It must be the name of a variable in the called process. If an empty string is specified here, the function returns the exit value of the zoom process. If the argument is not filled, the function returns nothing.
formpos
Specifies the form position for displaying the window. The default is 0
Note
This function is supported for backward compatibility only. In new applications, use start.session() instead.
Return value
The variable specified in the returnfld argument.
Context
Bshell function.
Use this function only in combination with the standard program.
Functions reference
40-9
Starting and stopping programs and sessions
Functions reference
40-10
Use these functions to manipulate strings in various ways. For example: n n n n n n n n n n
To check whether a string contains a long value or spaces
To check the number of characters or bytes in a string
To load numeric values stored in a string into variables of type long or double
To convert a number contained in a string to its numeric representation
To convert an integer or floating point number to a string
To convert a string to upper case or lower case
To search for a substring within a string
To strip leading and trailing spaces from strings
To align strings
To store a long or double in a string.
string concat$ long long isdigit isspace long long len len.in.bytes
long load.byte
double load.double
double load.float
long load.long
long long void long load.short
lval not.fixed
pos
( string separator, expr, ...)
( string_expr )
( string_expr )
( string_expr )
( string_expr )
( string record(long spos) )
( string record(long spos) [, long endian] )
( string record(long spos) [, long endian] )
( string record(long spos) [, long endian] )
( string record(long spos) [, long endian] )
( string_expr )
( string string_var(.) )
( string source(.), string pattern(.) )
Functions reference
41-1
String operations
long long long set.strip.mode
set.symbol.strip.
mode string shiftc$ string shiftl$ string shiftr$ void void void void void store.byte
store.double
store.float
store.long
store.short
string str$ string string.set$ string strip$ string tolower$ string toupper$ long tt.align.according.
domain double rpos val
( string source(.), string pattern(.) )
( long table_id, long mode )
( ref string str, long mode )
( string strg(.) )
( string strg(.) )
( string strg(.) )
( long lng, ref string rec )
( double dbl, ref string rec )
( double dbl, ref string rec )
( long lng, ref string rec )
( long lng, ref string rec )
( num_expr )
( string_expr, num_expr )
( string strg(.) )
( string_expr )
( string_expr )
( string string_in(.), ref string string_out(), string domain_name )
( string_expr )
Syntax
string concat$( string separator, expr, ... )
Description
This converts one or more expressions to strings and merges the expressions into a single string. You can use string.scan() to split the string again into its individual parts.
This function is used mainly by the report processor to save unsorted records in a sequential file for subsequent sorting.
Functions reference
41-2
String operations
Arguments
separator
The separator to be placed between individual values in the merged string.
expr ...
One or more expressions of type long, double, or string.
Context
Bshell function.
Example
string ret(100) long a string b(5) double d a = 10 b = "hello" d = 1.123456
ret = concat$( "|",a*10,b,d ) | ret now contains
| "100|hello|1.123456"
Syntax
long isdigit( string_expr )
Description
This tests whether the result of string_expr contains a long value.
Return values
TRUE string contains a long
FALSE string does not contain a long
Context
Bshell function.
Functions reference
41-3
String operations
Example
string str1(20) if ( not isdigit(str1) ) then message( "’%s’ is not a number", str1 ) endif
Syntax
long isspace( string_expr )
Description
This tests whether the result of string_expr contains only spaces or is empty.
Return values
TRUE
FALSE string is empty or contains only spaces string is not empty and contains characters other than spaces
Context
Bshell function.
Example
string str1(20) if ( not isspace(str1) ) then message( "’%s’ is not empty", str1 ) endif
Syntax
long len( string_expr )
Description
This returns the number of characters in string_expr. For strings declared as
FIXED, the total length of the string is returned. For non-fixed strings, the
Functions reference
41-4
String operations
current length is returned. To retrieve the length of FIXED strings, excluding trailing spaces, use strip$().
Context
Bshell function.
Example
long lng string var(20) string fix(20) fixed var = "abc" fix = "abc" lng = len( var ) | Returns 3 lng = len( fix ) | Returns 20 lng = len( strip$(fix) ) | Returns 3
Syntax
long len.in.bytes( string_expr )
Description
This returns the number of bytes in string_expr. In the case of ASCII characters, the number of bytes equals the number of characters. In the case of multibyte characters, each character can consist of one or more bytes.
Context
Bshell function.
Functions reference
41-5
String operations
Syntax
long load.byte( string record(long spos) ) double load.double( string record(long spos) [, long endian]) double load.float( string record(long spos) [, long endian] ) long load.long( string record(long spos) [, long endian] ) long load.short( string record(long spos) [, long endian] )
Description
These load numeric values stored in a string into variables of type long or double. These functions are machine independent and can be used (for example) in network communications.
Arguments
record
The string containing the numeric value that must be loaded into the long or double variable.
spos
This indicates the start position in the string of the numeric value to be loaded.
endian
These functions assume that the data in record is stored in big endian order (highest byte first). Where an application protocol uses little endian format instead, set this optional argument to 1 to indicate this.
The load.byte() function does not support this argument.
Context
Bshell functions.
Example
| Load two longs from a string string longs(8) long long_high, long_low long_high = load.long( longs(1;4) ) long_low = load.long( longs(5;4) )
Functions reference
41-6
String operations
Syntax
long lval( string_expr ) double val( string_expr )
Description
These convert a string expression that consists of digits to its numeric representation. lval() converts its argument to an integer. If the string contains a floating point number, the result is truncated. val() converts its argument to a floating point number. lval() is faster than val().
Return values
The specified string converted to a long or floating point number. Or 0 if the result of string_expr cannot be converted to a number.
Context
Bshell functions.
Syntax
void not.fixed( string string_var(.) )
Description
You can fill a string with or without specifying a start position. If you specify a start position, unused positions in the string are filled with spaces. You can prevent the string from being filled out with spaces by calling not.fixed() before filling the string. Note that, when you assign a new value to the string variable, positions after the new value are not changed.
Note
This function does not work with variables declared as FIXED.
Context
Bshell function.
Functions reference
41-7
String operations
Example 1
string buf(10) buf(5) = "***" buf = "***"
| buf contains " *** "
| buf contains "***"
Example 2
string buf(10) not.fixed( buf ) buf(5) = "***" buf = "***"
| buf contains " ***"
| buf contains "*** ***"
(length = 10)
(length = 3)
(length = 7)
(length = 7)
Syntax
long pos( string source(.), string pattern(.) ) long rpos( string source(.), string pattern(.) )
Description
These return the start position of a specified substring (pattern) in a specified string (source). source and pattern can be either strings or string expressions.
start position relative to the beginning of the source string.
Return values
The start position of the substring in the string. Or 0 if the substring is not found.
Context
Bshell functions.
Example
long posno posno = pos("abcdabcd", "bcd") posno = rpos("abcdabcd", "bcd")
| posno contains 2
| posno contains 6
Functions reference
41-8
String operations
Syntax
long set.strip.mode( long table_id, long mode ) long set.symbol.strip.mode( ref string str, long mode )
Description
the table specified by table_id. set.symbol.strip.mode() sets or resets the ’stripon-assignment’ flag for the variable specified by str. The mode argument indicates whether the flag is to be set on or off. 1 indicates set flag on, 0 indicates set flag off.
Notes
These functions do not affect the actual contents of the fields or variable.
If set.strip.mode() is the first call on a particular table, the table structure will be loaded.
Return values
0 success
<0 error
Context
Bshell functions.
Example
table tttaad200 string s(100) string s2(100) fixed string s3(100) if( set.strip.mode(tttaad2200, 1) < 0 ) or
( set.symbol.strip.mode(s2, 1) < 0 ) then
| handle error endif db.first(tttaad200) s = tttaad200.user | s contains username without trailing
| spaces
Functions reference
41-9
String operations
s2 = s | s2 is fixed so username is filled out
| with spaces s3 = s2 | s3 contains username without trailing
| spaces
Syntax
string shiftc$( string strg(.) ) string shiftl$( string strg(.) ) string shiftr$( string strg(.) )
Description
These return the specified string with certain adjustments.
If there is an odd number of spaces, the extra space becomes a trailing space. The returned string always has the same length as the input string.
spaces. The length of the result is always the same as the length of the input string (this is not necessarily the declaration length).
Note
These functions do not change the input string.
Context
Bshell functions.
Example
shiftc$(" ABC ") | result " ABC " shiftl$(" ABC ") | result "ABC " shiftr$(" ABC ") | result " ABC"
Functions reference
41-10
String operations
Syntax
void store.byte( long lng, ref string rec ) void store.double( double dbl, ref string rec ) void store.float( double dbl, ref string rec ) void store.long( long lng, ref string rec ) void store.short( long lng, ref string rec )
Description
These store a variable of type long or double in a string. Note that the numeric values are not converted to strings (see str$()). Instead, the real, machinedependent, binary representation is used.
Context
Bshell functions.
Example
| Split a long into two shorts long source long high_part, low_part string tmp(4) store.long( source, tmp ) high_part = load.short( tmp(1;2) ) low_part = load.short( tmp(3;2) )
Syntax
string str$( num_expr )
Description
This converts an integer or floating point expression to a string.
Functions reference
41-11
String operations
Context
Bshell function.
Syntax
string string.set$( string_expr, num_expr )
Description
This returns a string that contains string_expr repeated num_expr times.
Bshell function.
Example
string st(80) st = string.set$("-", 10) | st contains "----------" st = string.set$( string.set$("-",3)&"+", 3 )
| st contains "---+---+---+" st = string.set$( chr(135), 5 ) | st contains 5 graphic symbols
Syntax
string strip$( string_expr )
Description
This returns a specified string without trailing spaces. The input string remains unchanged.
Context
Bshell function.
Example
strip$(" ABC ") | result " ABC"
Functions reference
41-12
String operations
Syntax
string tolower$( string_expr ) string toupper$( string_expr )
Description
functions return the converted string expression. The input string remains unchanged.
Note
These functions can handle multibyte characters.
Context
Bshell functions.
Syntax
long tt.align.according.domain( string string_in(.), ref string string_out(), string domain_name )
Description
This aligns a string according to the alignment method of a specified domain.
Arguments
string_in(.) string_out()
The input string. This must have the same length as the specified domain. If it is longer than the domain, its final characters are ignored.
The input string remains unchanged by the function.
The returned string, aligned according to the alignment method of the domain. This must be the same length as the specified domain.
Functions reference
41-13
String operations
domain_name
The name of the domain whose alignment method must be used to align the output string. The alignment method can be left, right, or centered.
Return values
0
-1 success domain not found or domain is not of type string or multibyte string
Context
3GL library function.
Example
table ttiitm001 domain tcitem item long ret item = " XY" ret = tt.align.according.domain(item, tiitm001.item, "tcitem")
| Result tiitm001.item (if left adjusted):
| "XY "
Functions reference
41-14
The Structure Chart Manager is a tool that displays graphical tree structures. The functions described in this section enable programmers to create tree structures and to subsequently change their attributes.
A tree structure displays a list of items as an indented outline that reflects the hierarchical relationship between the items. The items in the tree structure are referred to as nodes. The first node in the tree is referred to as the root node.
Nodes in a tree structure have a parent-child relationship. Each node can have a number of child nodes, which are indented below it in the tree structure. Every node, except the root node, has a parent node – that is, the node under which it is indented.
Each node has a node ID, which is its sequence number in the sequence of child nodes associated with a particular parent. Each node, except the root node, also has a parent ID, which is the ID of its parent node. The parent and node IDs of a node determine where the item is positioned within the tree structure.
Nodes must be created from the top down. That is, the parent node must be present before you can create a child node for that parent.
Communication between the client program and the Structure Chart Manager is full-duplex. This means that the client can send information to the server and the server can send information to the client, simultaneously.
The Structure Chart Manager uses bucket messages for interprocess communication. When it sends a bucket message to the client, the client receives an event of type EVTBUCKETMESSAGE. So the client program must contain a loop to handle these events.
You can retrieve the command parameter of an event by using the following statement: command = evt.bms.command(event)
Functions reference
42-1
Structure Chart Manager (tree structures)
The command parameter indicates the reason for the event. It can have any of the following values:
MSG.PUSH.BUTTON
Indicates that the user has clicked on a button in the
Structure Chart.
MSG.NODE.PRESS
Indicates that the user has clicked on a node of the
Structure Chart.
MSG.NODE.DPRESS
Indicates that the user has double-clicked on a node of the Structure Chart.
You use the following functions to retrieve data from the Structure Chart
Manager after a bucket message has been received: get.tree.node.press,
All colors must be composed by using the rgb() function. Or you can use one of the following predefined colors:
RGB.BLACK
RGB.BLUE
RGB.YELLOW
RGB.MAGENTA
RGB.GREEN
RGB.GRAY
RGB.RED
RGB.WHITE
RGB.CYAN
#include <bic_eis> void create.node
long void create.tree
create.tree.button
void void destroy.tree
get.tree.default
( string tree_name(25), stringparent_id(25), string node_id(25), string node_desc(80), long node_class [, long process_id ] )
( string tree_name(25), string tree_title(80) )
( string tree_name(25), long button_id, string button_desc(80) [, long process_id ] )
( string tree_name(25) [, long process_id ] )
( )
Functions reference
42-2
Structure Chart Manager (tree structures)
void void void void void void void void void void void get.tree.node.dpress
( ref long event(), ref long process_id, ref string node_id() ) get.tree.node.press
( ref long event(), ref long process_id, ref string node_id() ) get.tree.push.button
( ref long event(), ref long process_id, ref long button_id, ref string node_id() ) set.node.class
( string tree_name(25), string node_id(25), long node_class [, long process_id ] ) set.node.class.color
( string tree_name(25), long node_class, long class_color [, long process_id ] ) set.tree.background
set.tree.font
( string tree_name(25), long color [, long process_id ]
( string tree_name(25), long visible_level, long font [, long process_id ] ) set.tree.foreground
set.tree.linewidth
( string tree_name(25), long color [, long process_id ])
( string tree_name(25), long visible_level, long linewidth [, long process_id ] ) set.tree.name
view.tree
( string tree_name(25), string tree_title(80) [, long process_id ] )
( string tree_name(25), string node_id(25), long depth [, long process_id ])
Functions reference
42-3
Structure Chart Manager (tree structures)
Syntax
void create.node( string tree_name(25), string parent_id(25), string node_id(25), string node_desc(80), long node_class [, long process_id] )
Description
This adds a new node to a specified tree. The node_id, together with the
parent_id, determine where the new node is located in the tree.
Arguments
tree_name parent_id node_id node_desc
The name of the tree to which the node must be added.
The ID of the parent node. Specify an empty string as the parent
ID for the root node.
The ID for the new node.
A description for the node. This is the label displayed for the node in the tree structure.
node_class
This is a number, in the range 1 to 9, that indicates the node class that must assigned to the node. The node class determines the color in which a node is displayed. You can subsequently assign a different class to the node by calling set.node.class() .
You use set.node.class.color() to define node classes.
process_id
This optional argument indicates the process ID of the server to which the node must be added, as returned by create.tree(). If you do not include this argument, the node is added to all servers with the name specified in tree_name.
Context
3GL library function.
Functions reference
42-4
Structure Chart Manager (tree structures)
Syntax
long create.tree( string tree_name(25), string tree_title(80) )
Description
This starts the Structure Chart Manager for a specified tree. It returns the process
ID of the tree. If there is more than one tree with the same name, you can specify the process ID in the other functions in order to identify a particular tree. The process ID is the unique identifier of a tree.
Arguments
tree_name
The name of the tree to be started.
tree_title
The title of the tree. This is displayed in the main window.
Notes
The tree structure is displayed only after you have called view.tree().
Return values
>0
0 success; returns the process ID of the new tree error
Context
3GL library function.
Syntax
void create.tree.button(string tree_name(25), long button_id, string button_desc(80) [, long process_id])
Description
This adds a button to a specified tree. The client program can link a session or command to this button. An event is sent to the client when the user clicks on the button.
Functions reference
42-5
Structure Chart Manager (tree structures)
Arguments
tree_name button_id
The name of the tree to which the button must be added.
The unique ID of the new button.
button_desc
The text for the button’s label.
process_id
This optional argument indicates the process ID of the server to which the button must be added, as returned by create.tree(). If you do not include this argument, the button is added to all servers with the name specified in tree_name.
Context
3GL library function.
Syntax
void destroy.tree(string tree_name(25) [, long process_id])
Description
This ends the Structure Chart Manager for the specified tree.
Arguments
tree_name
The name of the tree that you want to kill.
process_id
This optional argument indicates the process ID of the tree that you want to end, as returned by create.tree(). If you do not include this argument, all trees with the name tree_name are killed.
Context
3GL library function.
Functions reference
42-6
Structure Chart Manager (tree structures)
Syntax
void get.tree.default()
Description
When the client receives a bucket message that cannot be retrieved with
function to remove the bucket message from the internal stack.
Context
3GL library function.
Syntax
void get.tree.node.dpress( ref long event(), ref long process_id, ref string node_id() )
Description
Use this function to retrieve data from the Structure Chart Manager after an
EVTBUCKETMESSAGE-type event, with a MSG.NODE.DPRESS command, has been received.
Arguments
event process_id node_id
The event containing the MSG.NODE.DPRESS command.
This returns the process ID of the Structure Chart Manager that sent the message.
This returns the ID of the relevant node.
Context
3GL library function.
Functions reference
42-7
Structure Chart Manager (tree structures)
Syntax
void, get.tree.node.press( ref long event(), ref long process_id, ref string node_id() )
Description
Use this function to retrieve data from the Structure Chart Manager after an
EVTBUCKETMESSAGE-type event, with a MSG.NODE.PRESS command, has been received.
Arguments
event process_id node_id
The event containing the MSG.NODE.PRESS command.
This returns the process ID of the Structure Chart Manager that sent the message.
This returns the ID of the relevant node.
Context
3GL library function.
Syntax
void get.tree.push.button( ref long event(), ref long process_id, ref long button_id, ref string node_id() )
Description
Use this function to retrieve data from the Structure Chart Manager after an
EVTBUCKETMESSAGE-type event, with a MSG.PUSH.BUTTON command, has been received.
Arguments
event process_id
The event containing the MSG.PUSH.BUTTON command.
This returns the process ID of the Structure Chart Manager that sent the message.
Functions reference
42-8
Structure Chart Manager (tree structures)
button_id node_id
The returns the ID of the relevant button.
This returns the ID of the relevant node.
Context
3GL library function.
Syntax
void set.node.class( string tree_name(25), string node_id(25), long node_class [, long process_id ] )
Description
Use this function to assign a different class to a particular node. The node class determines the color in which a node is displayed.
Arguments
tree_name node_id
The name of the tree to which the specified node belongs.
The ID of the node to which you want to assign a new class.
node_class
This is a number, in the range 1 to 9, that indicates the node class that must assigned to the node. You use
process_id
This optional argument indicates the process ID of the tree for which you want to change the class of the specified node. If you do not include this argument, the node class is changed for the specified node in all trees with the name tree_name.
Context
3GL library function.
Functions reference
42-9
Structure Chart Manager (tree structures)
Syntax
void set.node.class.color( string tree_name(25), long node_class, long class_color [, long process_id ] )
Description
The node class assigned to a node determines the color in which the node is displayed. You use this function to define the color for a specified node class.
You use set.node.class() to assign a class to a particular node.
Arguments
tree_name
The name of the tree for which the node class must be defined.
node_class
This is the identifier of the node class. It can be any number in the range 1 to 9.
class_color
This specifies the color for the node class. It consists of either a number returned by the rgb() function or one of the following predefined colors:
RGB.BLACK
RGB.MAGENTA
RGB.BLUE
RGB.GREEN
RGB.YELLOW RGB.GRAY
RGB.RED
RGB.WHITE
RGB.CYAN
process_id
This optional argument indicates the process ID of the tree for which the node class must be defined. If you do not include this argument, the new color is assigned to the specified node class in all trees with the name tree_name.
Context
3GL library function.
Functions reference
42-10
Structure Chart Manager (tree structures)
Syntax
void set.tree.background( string tree_name(25), long color
[, long process_id ] )
Description
This changes the background color of a specified tree.
Arguments
tree_name color process_id
The name of the tree whose background color you want to change.
This specifies the new background color for the tree. The value can be a number returned by the rgb() function or one of the following predefined colors:
RGB.BLACK
RGB.MAGENTA
RGB.BLUE
RGB.GREEN
RGB.YELLOW RGB.GRAY
RGB.RED
RGB.WHITE
RGB.CYAN
This optional argument indicates the process ID of the tree whose background color you want to change. If you do not include this argument, the new background color is applied to all trees with the name tree_name.
Context
3GL library function.
Syntax
void set.tree.font( string tree_name(25), long visible_level, long font [, long process_id ] )
Description
This changes the font used for nodes at a particular level in a specified tree. Use
Functions reference
42-11
Structure Chart Manager (tree structures)
Arguments
tree_name
The name of the tree for which you want to change the font.
visible_level
This is a number, in the range 1 to 3, that specifies the node level to which the new font is to be applied. Visible level 1 specifies the highest level currently visible in the tree. Visible level 3 specifies levels three and below. See view.tree().
font process_id
The font to be applied to the specified node level.
This optional argument indicates the process ID of the tree for which the font must be changed. If you do not include this argument, the new font is applied to the specified level in all trees with the name tree_name.
Context
3GL library function.
Example
long mask, font, proc_id long request(FNTMAXSIZE) long reply(FNTMAXSIZE) proc_id = create.tree("test", "Test Structure Chart Manager") mask = FNTHEIGHT + FNTWEIGHT + FNTSLANT fnt.weight(request) = FNTMEDIUM fnt.height(request) = 12 fnt.slant(request) = FNTROMAN font = load.font(current.display(), mask, request, reply) set.tree.font("test", 1, font, proc_id)
Syntax
void set.tree.foreground( string tree_name(25), long color
[, long process_id ] )
Description
This changes the foreground color of a specified tree.
Functions reference
42-12
Structure Chart Manager (tree structures)
Arguments
tree_name color
The name of the tree whose foreground color you want to change.
This specifies the new foreground color for the tree. The value can be a number returned by the rgb() function or one of the following predefined colors:
RGB.BLACK
RGB.BLUE
RGB.YELLOW
RGB.MAGENTA
RGB.GREEN
RGB.GRAY
RGB.RED
RGB.WHITE
RGB.CYAN
process_id
This optional argument indicates the process ID of the tree whose foreground color you want to change. If you do not include this argument, the new foreground color is applied to all trees with the name tree_name.
Context
3GL library function.
Syntax
void set.tree.linewidth( string tree_name(25), long visible_level, long linewidth [, long process_id ] )
Description
This changes the line width (in pixels) used for nodes at a particular level in a specified tree. The default line widths are: level 1 level 2 level 3 level 4
–
–
–
–
4 pixels
2 pixels
1 pixel
1 pixel
Functions reference
42-13
Structure Chart Manager (tree structures)
Arguments
tree_name
The name of the tree for which you want to change the line width.
visible_level
This is a number, in the range 1 to 3, that specifies the node level to which the new line width is to be applied. Visible level
1 specifies the highest level currently visible in the tree.
Visible level 3 specifies levels three and below. See
linewidth process_id
The new line width (in pixels) to be applied to the specified node level.
This optional argument indicates the process ID of the tree for which the line width must be changed. If you do not include this argument, the new line width is applied to the specified level in all trees with the name tree_name.
Context
3GL library function.
Syntax
void set.tree.name( string tree_name(25), string tree_title(80) [, long process_id ] )
Description
This changes the title of a specified tree.
Arguments
tree_name tree_title process_id
The name of the tree whose title you want to change.
This specifies the new title for the tree.
This optional argument indicates the process ID of the tree whose title you want to change. If you do not include this argument, the new title is applied to all trees with the name
tree_name.
Functions reference
42-14
Structure Chart Manager (tree structures)
Context
3GL library function.
Syntax
void view.tree( string tree_name(25), string node_id(25), long depth [, long process_id ] )
Description
This changes which levels are visible in a specified tree.
Arguments
tree_name node_id depth
The name of the tree whose visible levels you want to change.
This specifies the ID of node that you want to become the new root node of the visible part of the tree.
This specifies the number of levels that you want to be visible.
The recommended number of visible levels is four.
process_id
This optional argument indicates the process ID of the tree whose visible levels you want to change. If you do not include this argument, the new settings are applied to all trees with the name tree_name.
Context
3GL library function.
Functions reference
42-15
Structure Chart Manager (tree structures)
#include <bic_event>
#include <bic_gc>
#include <bic_eis>
#define
#define
#define
BUTN.ID.1
BUTN.ID.2
BUTN.ID.3
1
2
3 function main()
{ string tree.id(25) string tree.title(80) long process.id
} tree.id = "exm" tree.title = "Example Tree" process.id = init.main.tree(tree.id, tree.title) handle.event.loop() exit.main.tree(process.id) function long init.main.tree(string tree.id(25), string tree.title(80))
{ long process.id
|-- activate Tree Server process.id = create.tree(tree.id, tree.title)
|-- create nodes create.node(tree.id, "", "1", "Root", 1, process.id) create.node(tree.id, "1", "1.1", "Root Child 1", 2, process.id ) create.node(tree.id, "1", "1.2", "Root Child 2", 2, process.id ) create.node(tree.id, "1", "1.3", "Root Child 3", 3, process.id ) create.node(tree.id, "1.1", "1.1.1", "Root Child 1.1", 3, process.id) create.node(tree.id, "1.1", "1.1.2", "Root Child 1.2", 1, process.id) create.node(tree.id, "1.2", "1.2.1", "Root Child 2.1", 1, process.id) create.node(tree.id, "1.2", "1.2.2", "Root Child 2.2", 2, process.id)
Functions reference
42-16
Structure Chart Manager (tree structures)
create.node(tree.id, "1.3", "1.3.1", "Root Child 3.1", 1, process.id)
|-- create buttons create.tree.button(tree.id, BUTN.ID.1, "Button 1", process.id) create.tree.button(tree.id, BUTN.ID.2, "Button 2", process.id) create.tree.button(tree.id, BUTN.ID.3, "Button 3", process.id)
|-- change default colors set.tree.background(tree.id, RGB.WHITE, process.id) set.tree.foreground(tree.id, RGB.BLACK, process.id) set.node.class.color(tree.id, 1, RGB.GREEN, process.id) set.node.class.color(tree.id, 2, RGB.YELLOW, process.id) set.node.class.color(tree.id, 3, RGB.RED, process.id)
|-- show root node with 2 underlying levels view.tree(tree.id, "1", 3, process.id)
}
|-- return new process id return(process.id) function void exit.main.tree(string tree.id(25), long process.id)
{
|-- kill Tree Server destroy.tree(tree.id, process.id)
} function void handle.event.loop()
{ long event(EVTMAXSIZE) long process.id
long button.id
string node.id(25) while ( TRUE ) next.event(event) on case evt.type(event) case EVTBUCKETMESSAGE: on case evt.bms.command(event) case MSG.PUSH.BUTTON: get.tree.push.button(event, process.id, button.id, node.id) on case button.id
case BUTN.ID.1:
Functions reference
42-17
Structure Chart Manager (tree structures)
.
.
break
.
.
endcase
break case MSG.NODE.PRESS: get.tree.node.press(event, process.id, node.id)
.
.
break case MSG.NODE.DPRESS:
get.tree.node.dpress(event, process.id, node.id)
.
.
break default:
get.tree.default()
break endcase break
.
.
endcase endwhile
}
Functions reference
42-18
BaanERP provides several mechanisms for starting one session from another – these are zoom fields, synchronized sessions, and the 4GL start.session() function. This section discusses synchronized sessions and associated functions.
When two sessions are synchronized, actions performed on one session window have a direct effect on the other session window. BaanERP implements two synchronization models: n
Dialog synchronization n
Child synchronization
This synchronizes a multioccurrence parent session with a single-occurrence dialog session. Both sessions act on the same main table. The parent session can be a modeless multioccurrence display form or a modal multioccurrence zoom window.
When the user double-clicks on an occurrence in the parent session, the standard program automatically opens the synchronized dialog session (if it is not already open) and updates it with information from the selected record. Whether the dialog opens in edit or display mode depends on user authorization settings. The synchronized dialog is also opened automatically when the user initiates one of the following actions: insert record, edit record, or duplicate record.
When a record is saved in the synchronized dialog, the standard program automatically updates the occurrence in the parent window.
Functions reference
43-1
Synchronized sessions
Parent and child forms must be of the following types:
type 2 type 3 type 1 type 3 with single occurrence
Parent and child session settings must be as follows:
Session type
Start option
display
44 (get defaults)
Window type
Main session
list window yes
maintain
0 (no start option) synchronized dialog no
Normally, this is used to synchronize sessions that act on different main tables.
In this case, the primary key of the parent’s main table must be a subset of the primary key of the child’s main table.
For example, take an Orders table that lists client orders, and an Order lines table that lists order lines per order. The primary key of the Orders session is orderno.
The primary key of the Order lines session is orderlines.orderno. In the Order lines session, orderno is a foreign key that references the Orders table.
With child synchronization, you can synchronize a parent session that uses the
Orders table with a child session that uses the Order lines table. The user chooses a form command to open the child session from the parent session. So the user can view the order lines associated with the orders listed in the parent session.
This example illustrates both dialog synchronization and child synchronization.
n
Sessions 1 and 2 form a set linked by dialog synchronization. Sessions 3 and
4 form another set linked by dialog synchronization.
n
You open session 2 by double-clicking a record in session 1. Double-clicking a different record in session 1 updates session 2 with information from the newly selected record. You open session 4 by double-clicking a record in session 3. Double-clicking a different record in session 3 updates session 4 with information from the newly selected record.
Functions reference
43-2
Synchronized sessions
n
Sessions 1 and 3 form a set linked by child synchronization.
n
You open session 3 by selecting a form command in session 1. The records displayed in session 3 depend on the arguments of the function associated with the form command. You could, for example, program the synchronization in such a way that each time the user selects a new record in session 1 and activates the form command, session 3 is updated to display the child records of the selected record.
Functions reference
43-3
Synchronized sessions
void set.synchronized.dialog
( string sess_code )
long start.synchronized.child
( string sess_code [, string parent.var, string child.var ...]) long start.synchronized.child.with
( const long cmd ) long stop.synchronized.child
( long child.id ) long synchronize.with.child
( long child.id )
Syntax
void set.synchronized.dialog( string sess_code )
Description
This synchronizes a multioccurrence parent session with a single-occurrence dialog. Both sessions act on the same main table.
When the user double-clicks on an occurrence in the parent session, the synchronized dialog is updated with information from the selected record. The synchronized dialog also automatically opens when the user initiates any of the following actions: insert record, edit record, or duplicate record. When a record is saved in the synchronized dialog, the standard program updates the occurrence in the parent window.
When the synchronized dialog is opened or updated, the synchronized.reason variable (read-only) is set. This indicates the command that caused the synchronization. The possible values are: ADD.SET, DUPL.OCCUR,
MODIFY.SET, and DISPLAY.SET. This variable is available in all sections in the synchronized dialog session.
Arguments
sess_code
The session code of the single-occurrence dialog session.
Functions reference
43-4
Synchronized sessions
Context
4GL library function.
You call the function in the before.program section of the multioccurrence parent session.
Syntax
long start.synchronized.child( string sess_code [, string parent.var, string child.var ...] )
Description
Use this to synchronize two sessions that act on different main tables. The function starts the specified child session when the user chooses a particular form command in the multioccurrence parent session. The primary key of the parent’s main table must be a subset of the primary key of the child’s main table.
Although you normally use this function to synchronize sessions that act on different main tables, it is also possible to use it to synchronize sessions that act on the same main table.
Arguments
sess_code parent.var
child.var
The session code of the child session.
These are optional arguments. You use them to synchronize particular variables in the parent and child sessions. For example, to display in the child session only order lines for the order currently selected in the parent session.
For each variable to be synchronized, specify the name of the relevant field in the parent’s main table, followed by the name of the corresponding field in the child’s main table.
For each synchronization event (start.synchronized.child(),
the child session is refreshed, and the specified variables derive their values from the parent session.
Functions reference
43-5
Synchronized sessions
Return values
>0
0
-1 a unique identifier for the child process cannot start child argument error
Context
4GL library function.
Syntax
long start.synchronized.child.with( const long cmd )
Description
To start a synchronized child with a command other than the default synchronization command, call this function before calling
Although you normally use this function to synchronize sessions that act on different main tables, it is also possible to use it to synchronize sessions that act on the same main table.
Arguments
cmd
This specifies the ID of the required command.
Return values
The function returns the specified command or 0 if the command is illegal.
Context
4GL library function.
Functions reference
43-6
Synchronized sessions
Syntax
long stop.synchronized.child( long child.id )
Description
This ends a child session.
Arguments
child.id
The unique identifier for the child session to be stopped, as returned by start.synchronized.child() or start.synchronized.child.with().
Return values
0
<0 success error
Context
4GL library function.
Syntax
long synchronize.with.child( ref long child.id )
Description
This refreshes (that is, resynchronizes) a child session. If the specified child session does not exist, the child.id argument is set to 0 on return.
Arguments
child.id
The unique identifier for the child session to be refreshed, as returned by start.synchronized.child() or start.synchronized.child.with().
Return values
0
<0 success error
Functions reference
43-7
Synchronized sessions
Context
4GL library function.
declaration:
long field.proc
before.program:
field.proc = 0
...
function extern field.process() | called by Form Command
{
if field.proc then
synchronize.with.child( field.proc )
endif
| field.proc is a reference variable that is set to
| zero when child cannot be found
if not field.proc then
field.proc = start.synchronized.child( "ttadv4127m000",
"ttadv420.vers", "ttadv422.vers",
"ttadv420.rele", "ttadv422.rele",
"ttadv420.cust", "ttadv422.cust",
"ttadv420.cpac", "ttadv422.cpac",
"ttadv420.cmod", "ttadv422.cmod",
"ttadv420.flno", "ttadv422.flno" )
endif
}
Functions reference
43-8
Use these functions to retrieve system and user information.
string bse.dir$ string bse.release$ string bse.tmp.dir$ long long current.display
get.display.data
string getenv$ long group.exists
string hostname$ long long long is.administrator
ostype user.exists
( )
( )
( )
( )
( ref long server_data(SRVMAXSIZE) )
( string env_var(256) )
( const string groupname )
( )
( )
( )
( const string username )
Syntax
string bse.dir$( )
Description
This returns a string containing the name of the directory where the Baan
Software Environment is installed. The function uses the environment variable
BSE to retrieve the information. If this variable is not filled, bse.dir$() returns the string "/usr/bse".
Context
Bshell function.
Functions reference
44-1
System and user information
Syntax
string bse.release$( )
Description
This returns a string of 3 characters that contains the release number of BAAN
Tools. For example, "6.2".
Context
Bshell function.
Syntax
string bse.tmp.dir$( )
Description
This returns a string containing the name of the directory where temporary files can be created by the application. The function uses the environment variable
BSE_TMP to retrieve the information. If this environment variable is not filled,
is not filled, the function returns the string "/usr/tmp".
Note
To create temporary files with a unique name in the directory BSE.TMP.DIR, use the function call creat.tmp.file$( bse.tmp.dir$() ).
Context
Bshell function.
Functions reference
44-2
System and user information
Syntax
long current.display( )
Description
This returns the identification number of the current display. It is provided to support the use of multiple displays in future versions of the software. Currently it always returns zero (0)
Context
Bshell function.
Syntax
long get.display.data( ref long server_data(SRVMAXSIZE) )
Description
This retrieves information about the display server. It stores the information in the array server_data. The predefined constant SRVMAXSIZE indicates the maximum size of the array.
You can retrieve the information using a set of predefined variables:
Server type typesrv.type(server_data)
DSNOSERVER
DSBX
DSBA
DSBW
Display width
Display height srv.display.width(server_data) srv.display.height(server_data)
Display width in millimeters srv.display.width.mm(server_data)
Display height in millimeters srv.display.height.mm(server_data)
Functions reference
44-3
System and user information
Number of colors
srv.display.colors(server_data)
Microsoft operating system srv.display.os.type(server_data)
DSBW_WIN_311
DSBW_WIN_NT
DSBW_WIN_95
NT4
Note
The above variables are valid only after a call to get.display.data().
Context
Bshell function.
Example
long win_width, srv_data(SRVMAXSIZE) get.display.data( srv_data ) win_width = srv.display.width( srv_data ) / 2
.....
if srv.type( srv_data ) = DSBW then if srv.display.os.type( srv_data ) = DSBW_WIN_95 then
.....
endif endif
Syntax
string getenv$( string env_var(256) )
Description
This returns the value of a specified environment variable of the operating system. It returns an empty string if the variable is not available.
Context
Bshell function.
Functions reference
44-4
System and user information
Example
string name(15) name = getenv$("LOGNAME")
Syntax
long group.exists( const string groupname )
Description
This checks whether a specified group is defined on the system. Whether group names are case-sensitive or case-insensitive is a system-dependent feature.
Return values
1 (TRUE) group exists
0 (FALSE) group does not exist
Example
string groupid(12) groupid = getenv$( "GROUP" ) if not group.exists( groupid ) then mess( "First create group " & groupid &
" on the system and restart the installation", 0 ) exit() endif
Context
Bshell function.
Syntax
string hostname$( )
Description
This returns the host name of the local machine.
Functions reference
44-5
System and user information
If no host name is found, the function returns an empty string. If the host name is incorrect, the user can change it by setting the environment variable
BSE_HOSTNAME.
Context
Bshell function.
Example
field.ttaad410.syst: before.input: if isspace(ttaad410.syst) then ttaad410.syst = hostname$() endif
Syntax
long is.administrator()
Description
This checks whether or not the user that is running the bshell has administrator rights on the server that the bshell is running. On UNIX systems, the function returns TRUE if the user has root access to the system. On Windows NT systems, the function returns TRUE if the user belongs to the administrator group.
Return values
<>0 (TRUE) user has administrator rights
0 (FALSE) user does not have administrator rights
Context
3GL library function.
Functions reference
44-6
System and user information
Syntax
long ostype()
Description
This returns a long value that indicates the operating system environment. The possible values are:
OS_WINDOWS_NT
OS_WINDOWS_95
OS_UNIX
Windows/NT
Windows 95
All UNIX variants
Context
Bshell function.
Syntax
long user.exists( const string username )
Description
This checks whether a specified user is defined on the system. Whether user names are case-sensitive or case-insensitive is a system-dependent feature.
Return values
1 (TRUE) user exists
0 (FALSE) user does not exist
Context
Bshell function.
Functions reference
44-7
System and user information
Functions reference
44-8
Use these functions for handling database text fields.
Every text stored in the database has a text number. A text field that is included in a database table is referenced in the table by its text number. The text itself, its key words, and so on, are stored in a separate table.
The text_field, text_field_from, and text_field_to arguments must always contain a text field name. This name can be the name of a database field of type
DB.TEXT, or it can be the name of a variable of type long. In both cases, the name must be enclosed by quote marks. When using a variable, this must be declared as EXTERN because the functions use the text_field argument indirectly to store the text number of the specified text. Database text field names are automatically declared as external.
In the case of all text field transactions, you must commit the transaction yourself.
Functions reference
45-1
Text fields
long text.copy
long long long long long long long long text.copy.
between.companies
text.copy.
language text.defaults
text.delete
text.edit
text.present.
in.language
text.read
text.rewrite
( string text_field_to(17), string text_field_from(17), string kw1(17) mb, string kw2(17) mb, string kw3(17) mb, string kw4(17) mb, string tgroup(8), string edit_opt(15) )
( string text_field_to(17), string text_field_from(17), long source_company, long target_company, string kw1(17) mb, string kw2(17) mb, string kw3(17) mb, string kw4(17) mb, string tgroup(8), string edit_opt(15) )
( long textnr, string lang_from, string lang_to )
( string text_field(17), ref string tgroup(8), ref string edit_opt(15) )
( string text_field(17), string lang )
( string text_field(17), string lang, string kw1(17) mb, string kw2(17) mb, string kw3(17) mb, string kw4(17) mb, string tgroup(8), string edit_opt(15), long mode )
( long textnr, string lang [, ref long nr_lines ] )
( string text_field(17), string lang, ref string kw1(17) mb, ref string kw2(17) mb, ref string kw3(17) mb, ref string kw4(17) mb, ref string tgroup(8), ref string edit_opt(15), string tmp_file(256), long lock )
( string text_field(17), string lang, string kw1(17) mb, string kw2(17) mb, string kw3(17) mb, string kw4(17) mb, string tgroup(8), string edit_opt(15), string tmp_file(256) [, long bidi] )
Functions reference
45-2
Text fields
long long long text.to.buf
text.window
text.write
( string text_field(17), string lang, long nr_lines, ref string buf(,) [, long rtf.text] )
( string edit_opt(15), ref long start_column, ref long start_row, ref long number_columns, ref long number_rows )
( string text_field(17), string lang, string kw1(17) mb, string kw2(17) mb, string kw3(17) mb, string kw4(17) mb, string tgroup(8), string edit_opt(15), string tmp_file(256) [, long bidi] )
Syntax
long text.copy( string text_field_to(17), string text_field_from(17), string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15) )
Description
This makes a copy of the entire text of a specified text field, for all languages, and assigns it a new text number.
Arguments
text_field_to text_field_from
The name of the text field that must be copied.
kw1 to kw4 Use these arguments to specify key words for the new text.
If you specify one or more of these arguments as an empty string, the corresponding key word(s) are copied from the original text. It is possible, for example, to specify two new key words and to copy the other two from the original text.
tgroup
The name of the new text field. See “Overview” in Chapter
45, Text fields. This returns the text number for the new text field.
This specifies the name of the text group to which the new text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
Functions reference
45-3
Text fields
edit_opt
This specifies the type of window in which the text must be displayed.
Return values
>0
-1 success; returns the number of lines copied error; no permission for this text field
Example
This example copies the text from the text field tttxt008.help to a new text field named tttxt008.docu. A new text number is created for tttxt008.docu and this is returned in the first argument. Key words 1 and 2 are new. Key words 3 and 4 are copied from the original text.
ret=TEXT.COPY("tttxt008.docu", "tttxt008.help", "docu",
"help", "", "", "", "")
Context
3GL library function.
Syntax
long text.copy.between.companies( string text_field_to(17), string text_field_from(17), long source_company, long target_company, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15) )
Description
This copies the entire text of a specified text field, for all languages, from one company to another.
Arguments
text_field_to text_field_from
The name of the new text field. See “Overview” in Chapter
45, Text fields. This returns the text number for the new text field.
The name of the text field that must be copied.
Functions reference
45-4
Text fields
source_company
This specifies the source company.
target_company
This specifies the destination company.
kw1 to kw4
tgroup edit_opt
Use these arguments to specify key words for the new text.
If you specify one or more of these arguments as an empty string, the corresponding key word(s) are copied from the original text. It is possible, for example, to specify two new key words and to copy the other two from the original text.
This specifies the name of the text group to which the new text must be assigned. If you specify an empty string here, the text is assigned to the user’s default group.
This specifies the type of window in which the text must be displayed.
Return values
>0
-1 success; returns the number of lines copied error
Context
3GL library function.
Syntax
long text.copy.language( long textnr, string lang_from, string lang_to )
Description
This copies a specified text from one language to another.
Arguments
textnr
The text number of the text that must be copied.
lang_from
This specifies the language from which the text must be copied.
lang_to
This specifies the language to which the text must be copied.
Functions reference
45-5
Text fields
Return values
>0
0 success; returns the number of lines copied error; text not found for source language
Context
3GL library function.
Syntax
long text.defaults( string text_field(17), ref string tgroup(8), ref string edit_opt(15) )
Description
This retrieves the defaults for a specified text field.
Arguments
text_field
The name of the text field. See “Overview” in Chapter 45, Text fields. This returns the text number of the field.
tgroup edit_opt
This returns the default text group of the text.
This returns the default window type for the text.
Return values
0
-1
-2 success one default not found no permission
Context
3GL library function.
Functions reference
45-6
Text fields
Syntax
long text.delete( string text_field(17), string lang )
Description
This deletes a specified text.
Arguments
text_field
The name of the text field that must be deleted. See “Overview” in Chapter 45, Text fields. This returns the text number of the field.
lang
The language for which the text must be deleted. To delete the text for all languages, specify an empty string here. In this case, the text number and all attributes of the text are deleted from the text manager. This also happens if the language you specify is the only language for which the text exists.
Return values
>0
-1 success; returns the number of lines deleted error
Context
3GL library function.
Syntax
long text.edit( string text_field(17), string lang, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15), long mode )
Description
This opens an edit window in which the specified text can be edited. If text_field is an empty string, or if the text number associated with the specified text is 0,
Functions reference
45-7
Text fields
the text manager prompts the user to confirm whether or not a new text must be created. After editing, the text number is retrieved and returned in text_field.
Arguments
text_field lang kw1 to kw4 tgroup edit_opt mode
The name of the text field. See “Overview” in Chapter 45, Text fields. This returns the text number of the field.
The language for which the text is to be edited.
Use these arguments to specify the key words for the text.
This specifies the name of the text group to which the new text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
This specifies the type of window in which the text must be displayed.
This species the text mode. Possible values are:
1
3 read-only read and write
Return values
The text number. Or -1 if an error occurs.
Context
3GL library function.
Syntax
long text.present.in.language( long textnr, string lang [, ref long nr_lines ] )
Description
This tests whether a specified text is available in a specified language.
Functions reference
45-8
Text fields
Arguments
textnr lang
The text number of the relevant text.
The language for which you wish to test the availability of the text.
nr_lines
This optional argument returns the number of lines the text occupies in the specified language.
Return values
1 (true)
0 (false) text available in specified language text not available in specified language
Context
3GL library function.
Syntax
long text.read( string text_field(17), string lang, ref string kw1(17), ref string kw2(17), ref string kw3(17), ref string kw4(17), ref string tgroup(8), ref string edit_opt(15), string tmp_file(256), long lock )
Description
This reads a specified text and stores it in a temporary file.
Arguments
text_field lang
The name of the text field that must be read. See “Overview” in
Chapter 45, Text fields.
If the text number of the specified field is 0, a subprocess is started, which lists the texts associated with the current company and enables the user to select the text to be read.
If no text is found, or if you abort the subprocess, text_field returns 0. Otherwise, it returns the text number of the retrieved text.
The language for which the text must be retrieved.
Functions reference
45-9
Text fields
kw1 to kw4 tgroup edit_opt tmp_file lock
These return the key words associated with the specified text.
This returns the name of the text group to which the text is assigned.
This returns the default window type for the text.
The name of the file in which the text must be stored. If this is an empty string, no text is retrieved and the function returns 0.
By default, a lock is applied to the text field when it is read. To read the field without lock, set this argument to 0.
Return values
>0
0
-1 success; returns the number of lines read no text found or subprocess aborted no permission
Context
3GL library function.
Syntax
long text.rewrite( string text_field(17), string lang, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15), string tmp_file(256) [, long bidi] )
Description
This writes text from a specified file to a specified text field. The new text and new text attributes replace the existing text and text attributes.
Arguments
text_field lang
kw1 to kw4
The name of the text field to which the file must be copied. See
“Overview” in Chapter 45, Text fields. If the specified text does not exist, nothing happens and the function returns 0.
The language for which the text is to be rewritten.
Use these arguments to specify key words for the text.
Functions reference
45-10
Text fields
tgroup edit_opt tmp_file bidi
This specifies the name of the text group to which the text must be assigned. If you specify an empty string here, the text is assigned to the user’s default group.
This specifies the type of window in which the text must be displayed.
The name of the file where the new text is stored.
Use this optional argument to indicate the text alignment.
Possible values are: true text is right justified false text is left justified; this is the default option
Return values
>0
0
-1 success; returns the number of lines written to the text field no such text no permission for text group
Context
3GL library function.
Syntax
long text.to.buf( string text_field(17), string lang, long nr_lines, ref string buf(,) [, long rtf.text] )
Description
This stores the text of a specified text field in a two-dimensional string array.
Arguments
text_field
The name of the text field that must be retrieved. See “Overview” in Chapter 45, Text fields.
lang nr_lines
This specifies the relevant language.
This specifies the maximum number of lines that can be stored in the buffer.
Functions reference
45-11
Text fields
buf rtf.text
This specifies the buffer in which the text must be stored.
Set this argument to true if you want the text to be stored in RTF format instead of ASCII format. This is possible only when using a text group that supports RTF data.
Return values
>0
0
- 1 number of stored lines error no permission to store the text
Context
3GL library function.
Syntax
long text.window( string edit_opt(15), ref long start_column, ref long start_row, ref long number_columns, ref long number_rows )
Description
This returns information about a specified window type.
Arguments
edit_opt start_column
The name of the window type.
This returns the number of the column where the window starts.
start_row
This returns the number of the row where the window starts.
number_columns
This returns the number of columns in the window.
number_rows
This returns the number of rows in the window.
Return values
0
-1 success error; edit_opt not found
Functions reference
45-12
Text fields
Context
3GL library function.
Syntax
long text.write( string text_field(17), string lang, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15), string tmp_file(256) [, long bidi] )
Description
This adds a new text to the text manager and assigns a new text number to the text.
Arguments
text_field lang
kw1 to kw4
tgroup edit_opt tmp_file bidi
The name of the new text field. See “Overview” in Chapter 45,
Text fields. This returns the text number for the new field.
This specifies the language for the new text.
Use these arguments to specify key words for the text.
This specifies the name of the text group to which the text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
This specifies the type of window in which the text must be displayed.
The name of the file where the text for the new field is stored.
Use this optional argument to indicate the text alignment.
Possible values are: true text is right justified false text is left justified; this is the default option
Return values
>0
-1 success; returns the number of lines written error
Functions reference
45-13
Text fields
Context
3GL library function.
Functions reference
45-14
Use the mtime() function to measure elapsed time. Use the other functions to start and end timers that generate timer events. You can use these events, for example, to time out blocking event functions.
void long long long kill.timer
mtime set.alarm
set.timer
( long timer_id )
( )
( long msec )
( long msec )
Syntax
void kill.timer( long timer_id )
Description
This ends a specified timer.
Argument
timer_id
The timer identifier, as returned by set.timer() or set.alarm() when the timer was created.
Note
A timer automatically terminates when the process that started it ends.
Context
Bshell function.
Functions reference
46-1
Timers
Syntax
long mtime()
Description
This measures the time elapsed since the first mtime() call. The function is common to all processes within the same bshell. That is, when it is called by a process, the result is the number of milliseconds since the function was first called by a process in the same bshell.
Return values
The first call returns 0. Subsequent calls return the number of milliseconds since the first call. A negative value is returned if an error occurs.
Note
The maximum time frame that mtime() can measure is 2147483647 milliseconds
(approximately 596 hours).
Context
Bshell function.
Syntax
long set.alarm( long msec )
Description
This starts a timer that sends a single EVTTIMEREVENT event to the calling process after the number of milliseconds specified in the msec argument. The timer automatically ends after sending the event. The timer also ends automatically when the process ends or when the program explicitly kills it with
Return values
A unique identifier for the timer.
Functions reference
46-2
Timers
Note
The kill.timer() function uses the identifiers returned by this function to specify which timer it is terminating.
Context
Bshell function.
See also
Chapter 17, Events.
Syntax
long set.timer( long msec )
Description
This starts a timer that sends an EVTTIMEREVENT event to the calling process every msec milliseconds. The timer continues to send events until the process ends or until the program explicitly terminates the timer using kill.timer().
Return values
A unique identifier for the timer.
Note
The kill.timer() function uses the identifiers returned by this function to specify which timer it is terminating.
Context
Bshell function.
See also
Chapter 17, Events.
Functions reference
46-3
Timers
Example
tim.id = set.timer(2000) next.event( event ) on case evt.type( event ) case EVTTIMEREVENT: if (evt.timer.id(event) = tim.id ) message("My ’2000’ timer expired") endif break endcase
Functions reference
46-4
Use the create.extra.toolbar() function to add a secondary toolbar to a form.
Buttons on the toolbar represent form commands; they provide an alternative means of executing those commands.
You can create the button images yourself (as .gif files) or you can reuse existing images, where appropriate. Before you can add buttons to a secondary toolbar, you must move their .gif files to the $BSE/gif/gfd0002 directory.
Buttons on secondary toolbars are automatically disabled or enabled when the corresponding form commands are disabled or enabled (see
void create.extra.
toolbar
( string form_command, string gif_file [, string form_command, string gif_file ...] )
Syntax
void create.extra.toolbar( string form_command, string gif_file [, string form_command, string gif_file ...])
Description
This adds a secondary toolbar to a form.
Arguments
The buttons to be included on the toolbar are indicated by the function arguments. The arguments consist of one or more pairs of strings. In each pair, the first argument is the name of a form command; the second argument is the name of the .gif file that holds the required image.
Functions reference
47-1
Toolbars
To include a space between two groups of buttons, insert two empty strings in the argument list.
Return values
>0
0
-1 success toolbar not allowed in this type of session incorrect number of arguments
Context
4GL library function.
The most suitable location for this function is in the init.form section of your UI script.
Example
create.extra.toolbar( "check.out","checkout",
"", "",
"edit.script", "modify1",
"compile", "compile",
"", "",
"check.in", "checkin" )
Functions reference
47-2
Use the at.base() function to base one variable (the based variable) on another variable (the basic variable). Both variables then use the same memory area.
The two variables must be of the same type. The possible types are string, string array, long array, and double array.
The based variable must be declared as BASED. If the two variables are in different processes, the basic variable must be declared as EXTERN.
long at.base
long at.base
( basic_variable [, arg ...], based_variable
[, arg ...] )
( long process_id, string name(.) [, arg ...] based_variable [, arg ...] )
Syntax
long at.base( basic_variable [, arg ...], based_variable [, arg ...] )
Description
Use this function to base one variable (the based variable) on another variable
(the basic variable). The two variables then use the same memory area.
Arguments
basic_variable
The variable on which the based_variable is to be based.
You can pass arguments to this variable. These specify the start position of the based variable within the basic variable.
The default start position is 1.
Functions reference
48-1
Variables (based)
based_variable
The based variable. You can pass arguments to this variable.
These specify the length of the based variable. The length plus the start position must not exceed the length reserved for the basic variable.
If you pass the argument -1 to the variable, the based variable uses the memory space of the basic variable from the specified start position to the end position. If this argument is 0, the variable uses the memory space of the basic variable from the specified start position for the declared length of the based variable.
This variable must be declared as BASED.
Notes
If the variables are multidimensional long or double arrays, only the first element can differ in the declarations. This is because the array values are stored column by column.
Do not reallocate basic_variable (with alloc.mem()). Doing this can cause serious problems, such as a core dump or corrupted memory.
Context
Bshell process.
See also
at.base()
Example
In this example, the contents of the variable long_to_be_based(1, 1)
are equal to the value of basic_long(4, 1)
. That is, a matrix of 2 by 5 longs.
long basic_long(5, 5) long long_to_be_based(3, 5) based at.base(basic_long, 4, 1, long_to_be_based, -1, 0)
Functions reference
48-2
Variables (based)
Syntax
long at.base( long process_id, string name(.) [, arg ...], based_variable [, arg ...] )
Description
Use this function to base one variable (the based variable) on an external variable in another process (the basic variable). The two variables then use the same memory area.
Arguments
process_id name
The ID of the process in which the basic variable is declared.
This process must be started before the current process and must be ended after the current process.
The name of the external variable on which based_variable is to be based. You can pass arguments to this variable.
These specify start position of the based variable within the basic variable. The default start position is 1.
This variable must be declared as EXTERN.
based_variable
The based variable. You can pass arguments to this variable.
These specify the length of the based variable. The length plus the start position must not exceed the length reserved for the basic variable.
If you pass the argument -1 to the variable, the based variable uses the memory space of the basic variable from the specified start position to the end position. If this argument is 0, the variable uses the memory space of the basic variable from the specified start position for the declared length of the based variable.
This variable must be declared as BASED.
Notes
If the variables are multidimensional long or double arrays, only the first element can differ in the declarations. This is because the array values are stored column by column.
Functions reference
48-3
Variables (based)
If the process specified by process_id ends before the current process, the based variable can no longer be used. This is because the memory area allocated to the basic variable is freed. This can cause serious problems, such as a core dump or corrupted memory.
Context
Bshell process.
See also
at.base()
Example
Process 1
EXTERN string base_string(20,2,2)
Process 2
string string_to_be_based(20,2) based long proc_id1 proc_id1 = activate("session_name_of_process1") at.base( proc_id1, "base_string", string_to_be_based )
Functions reference
48-4
These functions provide a mechanism for checking changes to variables. The variables can be of type string, long, double, domain, or array.
You start the mechanism for a particular variable by calling on.change.check().
The current value of the variable becomes the checkpoint value for the checking mechanism. The variable is considered to have changed if its value differs from the checkpoint value. Using the checking mechanism slows down program execution.
Note that the report writer also uses these functions. And use of the functions in a report script can have unpredictable results.
long void void void changed not.curr
off.change.check
on.change.check
( variable )
( variable )
( variable )
( variable )
Syntax
long changed( variable)
Description
This compares the current value of the specified variable with its checkpoint value to determine whether or not the value has changed.
Note
This function returns TRUE only if the value of the variable has changed since the last time you called the function.
Functions reference
49-1
Variables (checking changes)
Return values
TRUE
FALSE variable has changed variable has not changed
Context
Bshell function.
Syntax
void not.curr( variable )
Description
This switches the current and previous values of the specified variable. This is considered a value change by the checking mechanism. So if you subsequently call changed(), that function will return TRUE.
Context
Bshell function.
Syntax
void off.change.check( variable )
Description
This switches off the checking mechanism for the specified variable. Changes to the variable are no longer monitored by the checking mechanism.
Context
Bshell function.
Functions reference
49-2
Variables (checking changes)
Syntax
void on.change.check( variable )
Description
This starts the checking mechanism by setting a checkpoint for the specified variable. The current value of the variable becomes the checkpoint value.
Context
Bshell function.
string city(10) city = "Paris" on.change.check( city ) | checkpoint value set to Paris city = "Rotterdam" on.change.check( city ) | checkpoint value now set to
| Rotterdam city = "Amsterdam" if ( changed(city) ) then not.curr( city ) message( "City is changed, old city is: %s",city )
| city is Rotterdam not.curr( city ) message( "New city is: %s",city )
| city is Amsterdam endif off.change.check(city)
Functions reference
49-3
Variables (checking changes)
Functions reference
49-4
Use these functions to access the variables of other processes. The variables can be of any type. They must be declared as external (with the keyword EXTERN).
long get.var
long get.indexed.var
long put.var
long put.indexed.var
long long import export
( long processno, "variable", ref variable )
( long processno, "variable", ref variable, long dim0 [, long dim1, long dim2, long dim3 ] )
( long processno, "variable", expression )
( long processno, "variable", expression, long dim0 [, long dim1, long dim2, long dim3 ] )
( "variable", ref variable )
( "variable", expression )
Syntax
long get.var( long processno, "variable", ref variable )
Description
This retrieves the value of the specified variable. The variable can be a single variable of any type or an array.
Functions reference
50-1
Variables (inter-process transfer)
Arguments
processno
The process from which the variable is to be retrieved. You can specify the process ID, or you can use the predefined variables
variable
The name of the variable to be retrieved (this must be a lower case string). Alternately, you can specify a variable in which the name is stored.
variable
This stores the value of the retrieved variable.
Return values
0
1 error success
Context
Bshell function.
Example
extern domain ttaad.cjob cjob form.1: init.form: get.var( parent, "cjob", ttaad500.cjob )
Syntax
long get.indexed.var( long processno, "variable", ref variable, long dim0 [, long dim1, long dim2, long dim3 ] )
Description
This retrieves the value of the specified variable. It is the same as get.var() except that it enables retrieval of individual array elements.
Functions reference
50-2
Variables (inter-process transfer)
Arguments
processno variable
The process from which the variable is to be retrieved. You can specify the process ID, or you can use the predefined variables pid or parent.
The name of the variable to be retrieved (this must be a lower case string). The variable can be a single variable or an array and must be declared as external. Instead of specifying the variable name, you can specify a variable in which the name is stored.
variable
This stores the value of the retrieved variable or array element.
dim0 to dim3 Use these to specify a particular array element to be retrieved.
To retrieve a single variable, set dim0 to 1 and omit the other dim arguments.
Return values
2
3
0
1
4 success general error incorrect number of dimensions variable not found array element not available
Context
Bshell function.
Functions reference
50-3
Variables (inter-process transfer)
Example
extern long ltbl(10,5) extern string block(10,5,5) string ret_str(10) long ret_lng long e ltbl(1,1) = 1 ltbl(2,2) = 2 ltbl(3,3) = 3 block(1,1,1) = "The" block(1,1,2) = "quick" block(1,2,1) = "brown" block(1,2,2) = "jumps" e = get.indexed.var( pid, "block", ret_str, 1, 2 )
| ret_str contains "quick " e = get.indexed.var( pid, "ltbl", ret_lng, 3, 3 )
| ret_lng is equal to 3
Syntax
long put.var( long processno, "variable", expression )
The assigns a new value to a specified variable in another process. The variable can be a single variable of any type or an array.
Arguments
processno variable
The process to which the destination variable belongs. You can specify the process ID, or you can use the predefined variables
The name of the external variable in the other process (this must be a lower case string). Alternately, you can specify a variable in which the name is stored.
expression
The value to be assigned to the variable. If this is not the same type as the destination variable, it will be converted.
Functions reference
50-4
Variables (inter-process transfer)
Return values
0
1 error; probably variable not found success
Syntax
long put.indexed.var( long processno, "variable", expression, long dim0 [, long dim1, long dim2, long dim3 ] )
The assigns a new value to a specified variable in another process. It is the same as put.var() except that it enables a value to be assigned to an individual array element.
Arguments
processno variable expression
The process to which the destination variable belongs. You can specify the process ID, or you can use the predefined variables pid or parent.
The name of the external variable in the other process (this must be a lower case string). Alternately, you can specify a variable in which the name is stored.
The value to be assigned to the variable. If this is not the same type as the destination variable, it will be converted.
dim0 to dim3
Use these to specify a particular array element to which the new value is to be assigned. To assign a single variable value, set dim0 to 1 and omit the other dim arguments.
Return values
2
3
0
1
4 success general error incorrect number of dimensions variable not found array element not available
Functions reference
50-5
Variables (inter-process transfer)
Example
extern string tst_str(25) extern long ltbl(10,5) string ret_str(10) long ret_lng long e ret_str = "Hello" e = put.indexed.var( pid, "tst_str", ret_str, 1 ) ret_lng = 8 e = put.indexed.var( pid, "ltbl", ret_lng, 1, 1 ) ret_lng = 10 e = put.indexed.var( pid, "ltbl", ret_lng, 1, 2 ) ret_lng = 4 e = put.indexed.var( pid, "ltbl", ret_lng, 2, 1 ) ret_lng = 2 e = put.indexed.var( pid, "ltbl", ret_lng, 2, 2 )
| table is filled as follows:
| ltbl(1,1) = 8
| ltbl(1,2) = 10
| ltbl(2,1) = 4
| ltbl(2,2) = 2
Syntax
long import( "variable", ref variable )
Description
This is equivalent to: get.var( parent, "variable", ref variable )
.
Functions reference
50-6
Variables (inter-process transfer)
Syntax
long export( "variable", ref variable )
Description
This is equivalent to: put.var( parent, "variable", ref variable )
.
Functions reference
50-7
Variables (inter-process transfer)
Functions reference
50-8
BaanERP Tools provides a library of user interface objects and subobjects that you can use as the building blocks for a complete graphical user interface. The available object types include windows, graphs, graphical images, and a wide range of user interface controls such as menu bars, toolbars, scroll bars, list boxes, check boxes, and so on. The available subobjects consist of graphical parts, such as arcs, lines, and rectangles, which you can create in graphical windows.
Each object and subobject includes a set of attributes that defines its appearance and state. BaanERP Tools provides a set of functions that you can use to create and manipulate objects and subobjects, and to set and retrieve their attributes.
Each object and subobject has an identification number that is unique for all bshell processes.
Notes
You must always use the rgb() function to compose colors.
In the lists of attributes for each object type, the following flags are used:
C You can define the attribute when creating the object with the functions
S
G
You can define the attribute when changing the object with the functions
You can read the attribute with the functions get.object() or
Q You can query the attribute with the functions query.object() or
Functions reference
51-1
User interface objects
void change.object
void change.sub.object
( long object, long sub_object_id
[, long attribute, value [, size] ] ... ) long compress.pixmap
( long object_id [, long attribute, value [, size] ] ...)
( long colormap(), long num_colors, string pixmap(), long width, long height, ref string buffer(), ref long buffer_length ) long create.object
( long type, long parent_object [, long attribute, value [, size] ]
... ) long create.sub.object
( long object, long type, [, long attribute, value [, size] ] ...) long create.sub.object.
by.id
( long object, long sub_object_id, long type [, long attribute, value [, size] ] ... ) long decompress.pixmap
( string buffer(), ref long colormap(), ref string pixmap()) void destroy.object
( long object_id ) void destroy.sub.object
( long object, long sub_object_id) long get.object
( long object_id [, long attribute, ref value [, ref value] ] ... ) long get.pixmap.info
long get.sub.object
( ref string buffer(), ref long num_colors, ref long width, ref long height )
( long object, long sub_object_id
[, long attribute, ref value [, ref size] ] ... ) void inherit.object
void lower.object
void map.object
long query.object
( long process_nr, long object_id)
( long object_id )
( long object_id )
( long object_id [, long attribute, value [, size] ] ...
[, long attribute, ref value [, ref size] ] ... )
Functions reference
51-2
User interface objects
long query.sub.object
void void void void void void raise.object
set.focus
set.sensitive
unmap.object
unset.focus
update.object
( long object_id, long sub_object_id [, long attribute, value [, size] ] ... [, long attribute, ref value [, ref size] ] ... )
( long object_id )
( long object_id )
( long object_id, long status )
( long object_id )
( long object_id )
( long object_id )
DsCbarMenu
DsCcheckBox
DsCcolorCell
DsCcolormap
DsCcomBox
DsCdDComBox
DsCdDListBox
DsCdrawnButton
DsCfield
DsCfontSet
DsCframe
DsCgc
DsCgraph
DsCgrid
DsCgwindow
This table lists all the available object and subobject types. It also indicates which object types support child objects. Note that only the DsCgwindow object supports subobjects.
yes no no no yes no no no no no no no no
no no
DsCgpArc
DsCgpComposite
DsCgpGroupBox
DsCgpHeader
DsCgpImage
DsCgpLine
DsCgpOleSite
DsCgpPie
DsCgpPolygon
DsCgpPolyline
DsCgpRectangle
DsCgpText no no no no no no no no no no
no no
Functions reference
51-3
User interface objects
DsClabel
DsClistBox
DsCmwindow
DsCpixmap
DsCpushButton
DsCradioBox
DsCradioButton
DsCrowColumn no yes
DsCscrollWindow yes
DsCscrollbar no yes no no yes
no no
DsCslider
DsCstatusBar
DsCtabFrame
DsCtemplate
DsCtoolBar
DsCtree no no yes no no no
Functions reference
51-4
User interface objects
Syntax
void change.object( long object_id [, long attribute, value
[, size] ] ... )
Description
This changes the attribute values of the specified object.
Arguments
object_id attribute, value, size
The object ID, as returned by create.object() when the object was created.
Use these arguments to set new values for the object’s attributes. For each attribute you specify, you must include the attribute type (for example, DsNmaximum or
DsNminimum), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Context
Bshell function.
Syntax
void change.sub.object( long object, long sub_object_id [, long attribute, value [, size] ] ... )
Description
This changes the attribute values of the specified subobject.
Arguments
object
The ID of the parent object, as returned by create.object() when the parent object was created.
Functions reference
51-5
User interface objects
sub_object_id attribute, value, size
The ID of the subobject, as returned by create.sub.object() or create.sub.object.by.id() when the subobject was created.
Use these arguments to set new values for the subobject’s attributes. For each attribute you specify, you must include the attribute type (for example, DsNgcBackground or
DsNgcForeground), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Context
Bshell function.
Syntax
long compress.pixmap( long colormap(), long num_colors, string pixmap(), long width, long height, ref string buffer(), ref long buffer_length )
Description
This converts a specified colormap and pixmap to a picture in .gif format.
Arguments
colormap num_colors pixmap()
The ID of the DsCcolormap object that must be converted.
The number of colors defined by the specified colormap object.
The ID of the DsCpixmap object that must be converted.
width height
The width of the pixmap, in pixels.
The height of the pixmap, in pixels.
buffer
This returns the data for the .gif picture. To access the .gif
picture, you must write the buffer data to a file by calling
buffer_length
This returns the length of the buffer.
Functions reference
51-6
User interface objects
Return values
TRUE (!=0) success
FALSE (=0) error
Context
Bshell function.
Syntax
long create.object( long type, long parent_object [, long attribute, value [, size] ] ... )
Description
This creates a new object of the specified type.
Arguments
type parent_object attribute, value, size
The type of object to be created. For example,
The ID of the parent object. You must create an object within a parent object. The parent object can be a main window, another object, or the current display.
Use these optional arguments to set the object’s attributes.
For each attribute you specify, you must include the attribute type (for example, DsNmaximum or
DsNminimum), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Return values
The ID for the new object, or 0 if an error occurs. You can subsequently use the returned ID as the object_id, parent_object, or object argument in other functions.
Context
Bshell function.
Functions reference
51-7
User interface objects
Syntax
long create.sub.object( long object, long type [, long attribute, value [, size] ] ... )
Description
This creates a new subobject of the specified type. The subobject is drawn on the parent window. If the parent object is destroyed, its subobjects are also destroyed.
Arguments
object type attribute, value, size
The ID of the parent object, as returned by create.object() when the parent object was created. The parent object is always a DsCgwindow object.
The type of subobject to be created. For example,
Use these arguments to set the subobject’s attributes. For each attribute you specify, you must include the attribute type (for example, DsNgcBackground or
DsNgcForeground), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Return values
The ID for the new subobject or 0 if an error occurs. You can subsequently use the returned ID as the sub_object_id argument in other functions.
Context
Bshell function.
Functions reference
51-8
User interface objects
Syntax
long create.sub.object.by.id( long object, long sub_object_id, long type [, long attribute, value [, size ] ] ... )
Description
This creates a new subobject with a specified ID. The subobject is drawn on the parent window. If the parent object is destroyed, its subobjects are also destroyed.
Arguments
object sub_object_id type attribute, value, size
The ID of the parent object, as returned by create.object() when the parent object was created. The parent object is always a DsCgwindow object.
The ID for the new object.
The type of subobject to be created. For example,
Use these arguments to set the subobject’s attributes. For each attribute you specify, you must include the attribute type (for example, DsNgcBackground or
DsNgcForeground), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Return values
The ID for the new subobject (as specified by the sub_object_id argument) or 0 if an error occurs. You can subsequently use the returned ID as the sub_object_id argument in other functions.
Context
Bshell function.
Functions reference
51-9
User interface objects
Syntax
long decompress.pixmap( string buffer(), ref long colormap(), ref string pixmap() )
Description
This converts a picture in .gif format to a colormap and pixmap. The long array returned by the colormap argument can subsequently be used as the
DsNcolorTable attribute of a DsCcolormap object. The string array returned by the pixmap argument can subsequently be used as the DsNdata attribute for a
Arguments
buffer
The buffer containing the .gif file data, as returned by a seq.read() call.
colormap
This returns an array of rgb values that you can use as the
DsNcolorTable attribute for DsCcolormap objects.
pixmap
This returns an array of indexes into the returned colormap. You can use this as the DsNdata attribute of DsCpixmap objects.
Return values
TRUE (!=0) success
FALSE (=0) error
Context
Bshell function.
Syntax
void destroy.object( long object_id )
Description
This removes the specified object and all its children (if any).
Functions reference
51-10
User interface objects
Arguments
object_id
The object ID, as returned by create.object() when the object was created.
Context
Bshell function.
Syntax
void destroy.sub.object( long object, long sub_object_id )
Description
This removes the specified subobject.
Arguments
object
The ID of the parent object, as returned by create.object() when the parent object was created.
sub_object_id
The ID of the subobject, as returned by create.sub.object() or
Context
Bshell function.
Syntax
long get.object( long object_id [, long attribute, ref value [, ref size] ] ... )
Description
This retrieves information about a specified object.
Functions reference
51-11
User interface objects
Arguments
object_id
The object ID, as returned by create.object() when the object was created.
attribute
The attribute you want to retrieve (for example, DsNtitle or
DsNbackground).
value size
This returns the current value of the specified attribute.
For attributes of type void data and long array, this returns the size of the data or array.
Return values
TRUE
FALSE success error
Context
Bshell function.
Syntax
long get.pixmap.info( ref string buffer(), ref long num_colors, ref long width, ref long height )
Description
This retrieves information about a picture, in .gif format, that has been read with the seq.read() function. It returns the number of colors in the picture and the picture’s width and height. When a picture is used in an object, the width and height values are necessary for determining the amount of memory that must be allocated for the picture.
Arguments
buffer
The buffer containing the data retrieved by seq.read().
num_colors
This returns the number of colors used in the picture.
width height
This returns the width of the picture, in pixels.
This returns the height of the picture, in pixels.
Functions reference
51-12
User interface objects
Return values
TRUE success
FALSE error
Context
Bshell function.
Syntax
long get.sub.object( long object, long sub_object_id [, long attribute, ref value [, ref size] ] ... )
Description
This retrieves information about a specified subobject.
Arguments
object
The ID of the parent object, as returned by create.object() when the object was created.
sub_object_id
The ID of the subobject of the specified parent object.
attribute
The attribute you want to retrieve (for example,
DsNgcBackground or DsNgcForeground).
value size
This returns the current value of the specified attribute.
For attributes of type void data and long array, this returns the size of the data or array.
Return values
TRUE
FALSE success error
Context
Bshell function.
Functions reference
51-13
User interface objects
Syntax
void inherit.object( long process_nr, long object_id )
Description
With this function, a process can inherit an object from its parent process. For example, a zoom process can use a pushbutton that was defined in the parent process.
Arguments
process_nr
The process ID of the parent process.
object_id
The ID of the object that must be inherited.
Context
Bshell function.
Syntax
void lower.object( long object_id )
Description
This moves the specified object to the bottom of the object stack on the workspace.
Context
Bshell function.
Functions reference
51-14
User interface objects
Syntax
void map.object( long object_id )
Description
This makes the specified object visible, without changing the order of the objects on the workspace.
Context
Bshell function.
Syntax
long query.object( long object_id [, long attribute_in, value_in [, size_in] ] ... [, long attribute_in, ref value_out [, ref size_out] ] ... )
Description
This retrieves information about a specified object, based on specified attribute values. For example, you can query a DsCgwindow object for the ID of the subobject that is located at specified x- and y-coordinates within the gwindow.
Or you can query a DsCgrid object for the type of control that a specified column contains.
Arguments
object_id attribute_in, value_in, size_in
The ID of the object to be queried, as returned by
You can use one or more sets of these arguments to specify the input attributes for the query. For each attribute you specify, you must include the attribute type (for example,
DsNcolumns), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Functions reference
51-15
User interface objects
attribute_in, value_out, size_out
You can use one or more sets of these arguments to specify the output of the query. For each attribute you specify, you must include the attribute type (for example, DsNcontrol).
The function returns the current value of the attribute. For attributes of type void data or long array, it also returns the size of the data or array.
Return values
TRUE
FALSE success error
Context
Bshell function.
Examples
The following are examples of some of the situations in which you can use the
1
To retrieve the ID of the subobject located at a specified position within a graphical window. If there is more than one subobject at the specified location, the function returns the ID of the uppermost subobject.
long mwin_id, gwin_id, gp1, gp2, gp3, part mwin_id = create.object( DsCmwindow, current.display(),
DsNbackground, RGB.BLACK,
DsNminHeight, 400,
DsNminWidth, 650,
DsNflags, DSNORMALSTATE+DSAUTORESIZE) gwin_id = create.object( DsCgwindow, mwin_id,
DsNbackground, RGB.BLUE,
DsNwidth, 200,
DsNheight, 100,
DsNx, 30,
DsNy, 30 ) update.object( gwin_id ) gp1 = create.sub.object( gwin_id, DsCgpRectangle,
DsNgcBackground, RGB.WHITE,
DsNheight, 50,
DsNwidth, 50,
DsNx, 0,
DsNy, 0 ) gp2 = create.sub.object( gwin_id, DsCgpArc,
DsNgcBackground, RGB.BLACK,
DsNheight, 20,
DsNwidth, 20,
Functions reference
51-16
User interface objects
DsNx, 10,
DsNy, 10 ) gp3 = create.sub.object( gwin_id, DsCgpLine,
DsNgcBackground, RGB.RED,
DsNxo, 1,
DsNyo, 1,
DsNxn, 1,
DsNyn, 200 ) update.object( mwin_id ) query.object( gwin_id,
DsNx, 20,
DsNy, 20,
DsNsubObject, part )
| part contains the value of gp2
2
To retrieve the IDs of the subobjects that occur within a particular area of a graphical window.
long part.list(20) | max. 20 parts
long num.parts
query.object( gwin_id,
DsNx, 5,
DsNy, 5,
DsNsize, 20, | maximum number of parts
DsNwidth, 30,
DsNheight, 30,
DsNsubObjectArray, part.list, num.parts )
The num.parts argument now contains the number of subobjects that occur within the specified area (in this case, 2). The part.list array contains the IDs of the subobjects (in this example, it contains the IDs of gp1 and gp2).
3
To retrieve the ID of the subobject that in on the top of the subobject stack. If the DsCgwindow object does not contain any parts, 0 is returned.
query.object( gwin_id, DsNfirstSubObject, part )
| part contains the ID of gp1
4
To retrieve the ID of the subobject on the bottom of the subobject stack. If the DsCgwindow object does not contain any parts, 0 is returned.
query.object( gwin_id, DsNlastSubObject, part )
| part contains the ID of gp3
5
To retrieve the ID of the subobject that follows a specified reference subobject in the subobject stack. The stack is built from top to bottom. So the function returns the ID of the subobject below the reference subobject. If the reference subobject is the last subobject in the stack, 0 is returned.
Functions reference
51-17
User interface objects
query.object( gwin_id, DsNrefSubObject, gp2,
DsNnextSubObject, part )
| part contains the ID of gp3
6
To retrieve the ID of the subobject that precedes the specified reference subobject in the subobject stack. The stack is built from top to bottom. So the function returns the ID of the subobject above the reference subobject. If the reference subobject is the first subobject in the stack, 0 is returned.
query.object( gwin_id, DsNrefSubObject, gp2,
DsNprevSubObject, part )
| part contains the ID of gp1
Syntax
long query.sub.object( long object_id, long sub_object_id
[, long attribute_in, value_in [, size_in] ] ... [, long attribute_in, ref value_out [, ref size_out] ]
... )
Description
This retrieves information about a specified subobject, based on specified attribute values. For example, you can query a DsCgpOleSite subobject for data in a specific format.
Arguments
object_id
The ID of the object to which the subobject belongs.
sub_object_id
The ID of the subobject within the specified object.
attribute_in, value_in, size_in
You can use one or more sets of these arguments to specify the input attributes for the query. For each attribute you specify, you must include the attribute type and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
attribute_in, value_out, size_out
You can use one or more sets of these arguments to specify the output of the query. For each attribute you specify, you must include the attribute type. The function returns the current value of the attribute. For attributes of type void data or long array, it also returns the size of the data or array.
Functions reference
51-18
User interface objects
Return values
TRUE success
FALSE error
Context
Bshell function.
Syntax
void raise.object( long object_id )
Description
This moves the specified object to the top of the object stack on the workspace.
Context
Bshell function.
Syntax
void set.focus( long object_id )
Description
This moves the keyboard input focus to the specified object. When an object has input focus, all keyboard input within the object’s main window is received by that object, regardless of the position of the cursor. When an object has input focus, it is surrounded by a rectangular highlight.
Context
Bshell function.
Functions reference
51-19
User interface objects
Syntax
void set.sensitive( long object_id, long status )
Description
This sets the sensitivity of a specified object.
Arguments
object_id
The ID of the object.
status
The status that must be set for the object. Possible values are:
DSSETSENSITIVE
DSSETINSENSITIVE
When the status of an object is set to insensitive, the object and its children are disabled.
Context
Bshell function.
Syntax
void unmap.object( long object_id )
Description
This makes the specified object invisible.
Context
Bshell function.
Functions reference
51-20
User interface objects
Syntax
void unset.focus( long object_id )
Description
This removes keyboard input focus from the specified object.
Context
Bshell function.
Syntax
void update.object( long object_id )
Description
This (re)draws the specified object. Some changes made to DsCgwindow and
Context
Bshell function.
Functions reference
51-21
User interface objects
Description
A DsCbarMenu object defines a menu bar and associated drop-down and cascaded menus. The menu bar is displayed across the top of a main window
(DsCmwindow), below the title bar.
An application creates the entire menu with a single create.object() call.
Subsequently, it can use change.object() to add, remove, change, enable, and disable menu items.
Remember to specify the identification number of the DsCbarMenu object in the DsNbarMenu attribute of the parent window.
Events
A DsCbarMenu object can generate the following event type:
EVTMENUSELECT
Functions reference
51-22
User interface objects
Attributes
DsNcommandList
(long array)
DsNeventMask
(long)
DsNfunction
(long)
[CS] Use this to set the state of menu items and to remove menu items. The array contains one or more index/attribute pairs. The index is an index into the list created by DsNmenuData. The menu entry identified by each index (1-based) is set to the associated attribute value. Possible attribute values are:
DSMENUNORMAL
DSMENUDISABLED
DSMENUCHECKED
DSMENUREMOVE
DSMENURADIOBUTTON
You can modify or remove multiple menu items with a single change.object() call.
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CS] Specifies whether menu items are to be added before or after the point specified by
DsNrefCommand. Possible values are:
DSMENUINSERT (default)
DSMENUAPPEND
Functions reference
51-23
User interface objects
DsNmenuData
(void)
DsNobjectType
(long)
DsNparent
(long)
DsNrefCommand
(long)
[CSG] This contains the menu data in binary format.
The data includes the structure of the menu, menu item names, shortcut and access keys, and the state and ID (return value) of menu items.
The data must start with a header containing the following fields: long long
Version number (currently always 1).
Number of entries to follow.
This is followed by multiple entries in the following format: long long string long
Menu hierarchy level.
Unique command identifier.
Separators must always be assigned an ID of -1; cascaded menu entries must always be assigned an ID of 0.
Null terminated name string (mb).
State of menu items – possible values are:
DSMENUNORMAL
DSMENUDISABLED
DSMENUCHECKED
DSMENUREMOVE
DSMENURADIOBUTTON
You can use DsNmenuData to create a new menu and also to add items to existing menus.
[G] The object type.
[G]
[S]
[CS]
The ID of the parent object.
This contains the index (1-based offset) of the menu position where menu items are to be added or inserted.
The state of the object. See DsCmwindow.
DsNsetState
(long)
DsNtemplate
(long)
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-24
User interface objects
Examples
The following is an example of DsNmenuData data used to create a new menu:
1
2
1
2
2
2
2
1
2
2
2
2
1
0
15
-1
23
-1
37
0
17
-1
6
0
72
12
&File
&Save
-
&Print\tCtrl + P
-
E&xit\tAlt + F4
&Edit
&Undo
-
&Find...
&Help
&Contents
0
0
0
0
0
0
0
0
0
0
0
0
The following function call creates the menu specified in DsNmenuData: barmenu.id = create.object(barmenu_id, DsCbarMenu, parentWindow, DsNmenuData, data, size)
The following is an example of DsNmenuData used to add new entries to the menu:
1
2
2
2
90
901
&Redo
&Delete
0
0
The following function call adds the new entries after the Undo menu item: change.object(barmenu_id, DsNmenuData, data, size,
DsNrefCommand, 8, DsNfunction, DSMENUAPPEND)
Functions reference
51-25
User interface objects
The following code disables the Print menu item and removes the Undo menu item: long commandlist(4) commandlist(1) = 4 commandlist(2) = DSMENUDISABLE commandlist(3) = 8 commandlist(4) = DSMENUREMOVE
| index of Print menu item
| index of Undo menu item change.object(barmenu.id, DsNcommandList, commandlist, 4)
Description
A check box represents a choice that has two states (selected or not selected). It appears as a square box with an accompanying label. When the choice is selected, a check mark appears in the box. When the choice is not selected, the box is empty.
Users can toggle a check box on and off with the mouse or keyboard keys. Check boxes are typically used in a group to provide a multiple-choice field. Within a group, they represent independent choices that are not mutually exclusive.
Events
A DsCcheckBox object can generate the following event types:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTBUTTONSELECT
Functions reference
51-26
User interface objects
Attributes
DsNeventMask
(long)
DsNfontSet
(long)
DsNheight
(long)
DsNjustify
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNset
(long)
[CSG] Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the label text. If this attribute is not set, the
Windows default font is used.
[CSG] The height of the object, in pixels.
[CSG] The alignment of the label text. Possible values are:
DSJUSTIFYLEFT (default)
DSJUSTIFYRIGHT
DSJUSTIFYCENTER
[G] The object type.
[G]
[CS]
The ID of the parent object.
[CSG] The state of the check box. Possible values are:
TRUE Check box selected.
FALSE Check box not selected (default).
The state of the object. See DsCmwindow.
[CSG] The label text.
DsNsetState
(long)
DsNstring
(string)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
Functions reference
51-27
User interface objects
DsNy
(long)
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A color cell is a rectangular child window that displays a color. If possible, a color cell uses only one palette entry and so saves resources. Otherwise, the number of colors used increases with every change.
Events
A DsCcolorCell object does not generate events.
Attributes
DsNbackground
(long)
DsNborderWidth
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNsetState
(long)
DsNtemplate
(long)
DsNwidth
(long)
[CSG] The rgb value that defines the background color of the object. If this attribute is not specified, the object inherits the background color of its parent. If none of the parent objects specify a background color, the resource workAreaBackground is used.
[CSG] The width of the object’s border, in pixels.
[CSG] The height of the object, in pixels.
[G]
[G]
[CS]
The object type.
The ID of the parent object.
The state of the object. See DsCmwindow.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
Functions reference
51-28
User interface objects
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A color map defines an array of colors that can be used by a DsCpixmap object.
The DsNdata attribute of a pixmap object contains an array of indexes into the color table of a DsCcolormap object.
Events
A DsCcolormap object does not generate events.
Attributes
DsNcolorTable
(long array)
DsNobjectType
(long)
DsNparent
(long)
DsNtemplate
(long)
[CSG] An array of rgb values.
[G]
[G]
[CS]
The object type.
The ID of the parent object.
The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-29
User interface objects
Description
A list box (DsClistBox) displays a list of choices from which the user can select one or more items.
A drop-down list box (DsCdDListBox) also displays a list of choices, but the list is displayed only on demand and the user can select only a single item. Users must open the control to view the list. When the list is closed, the control displays the current value.
A combo box (DsCcomBox) is a combination of a text box and a single-selection list box. Users can type their choice in the text box or select an item from the list.
A drop-down combo box (DsCdDComBox) is a combination of a text box and a drop-down list box. Users can type their choice in the text box or select an item from the list. The list is displayed only on demand – that is, users must open the control to view the list. When the list is closed, the control displays the current value.
Functions reference
51-30
User interface objects
For all the above controls, vertical and/or horizontal scroll bars are displayed when the list box is not large enough to display all items in full.
Events
These objects can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTLISTBOXSELECT
Attributes
DsNallowMultiSelection
(long)
DsNcolumns
(long)
DsNeventMask
(long)
[CG]
Indicates whether a user can select more than one item. Possible values are:
TRUE
FALSE
Multiselection permitted.
Multiselection not permitted (default).
[CSG] The width of the list box, in characters.
The default is 0. Note that DsNwidth and
DsNcolumns are mutually exclusive attributes.
[CSG] Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
Functions reference
51-31
User interface objects
DsNfontSet
(long)
DsNheight
(long)
DsNitemCount
(long)
DsNmaxLength
(long)
DsNmaxWindowSize
(long)
DsNminWidth
(long)
DsNminWindowSize
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNselected
(long)
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the object’s text. If this attribute is not set, the Windows default font is used.
[G] The height of the object, in pixels.
[G] The total number of items in the list box.
This attribute is updated whenever an item is added or removed.
[CSG]
objects only.
The maximum number of input characters in the text field. This can be any value from 0 to 4096. The default is
4096.
[CSG] The maximum number of items the list box can contain.
[CSG] The minimum width of the list box, in pixels.
[CSG] The minimum number of items the window can contain.
[G] The object type.
[G]
[CS]
The ID of the parent object.
This determines the state of the items specified by DsNselectedId or
DsNselectionArray. Possible values are:
TRUE
FALSE
Items are selected.
Items are unselected.
This attribute is valid only when
DsNallowMultiSelection is TRUE.
Functions reference
51-32
DsNselectedId
(long)
DsNselectionArray
(long array)
DsNselectionCount
(long)
DsNsetState
(long)
DsNstring
(string array)
DsNstringArray
DsNtemplate
(long)
DsNwidth
(long)
User interface objects
[CSG] The item ID of the currently selected item. An item ID of -1 causes the list box to act in a special way. In a singleselection list, all items are unselected. In a multiselection list, all items are selected or unselected, depending on the value of
DsNselected.
[CSG]
The item IDs of all selected items in a multiselection list. The array length is 2 *
DsNselectionCount.
[G]
[CS]
The number of items currently selected in a multiselection list.
The state of the object. See
[CSG]
objects only.
The text to be displayed in the text box.
You can specify from 0 to 4096 characters. The default is an empty string.
[CS] This contains the text and ID of each item in the list box. The data must be filled as follows: itemstring + idstring + itemstring + idstring ...
All strings are null terminated.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
Functions reference
51-33
User interface objects
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCdrawnButton object has the same functionality as a DsCpushButton object except that it displays a graphical image instead of a text label.
Events
A DsCdrawnButton object can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTBUTTONSELECT
Attributes
DsNeventMask
(long)
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNpixmap
(long)
[G]
[G]
[CSG]
The object type.
The ID of the parent object.
The ID of the DsCpixmap object to be displayed on the button.
Functions reference
51-34
User interface objects
DsNreturnValue
(long)
[CSG] The value that will be returned when the button is selected. The return value must be handled as an event. See Chapter 17, Events.
[CS] The state of the object. See DsCmwindow.
DsNsetState
(long)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CS]
[CSG] The width of the object, in pixels.
[CSG]
[CSG]
The ID of a template object that defines a set of attributes to be applied to the object.
The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCfield object provides a rectangular child window where the user can enter and edit text. It can be defined to support a single line or multiple lines of text. A
referred to as an edit control).
Events
A DsCfield object can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTFIELDSELECT
Functions reference
51-35
User interface objects
Attributes
DsNcolumns
(long)
DsNconvertSoftReturn
(long)
DsNeditable
(long)
DsNeditMode
(long)
DsNeventMask
(long)
DsNfieldData
(void)
[CSG] The width of the text box, in characters.
For proportional fonts, the width is based on the widest character of the font.
DsNwidth and DsNcolumns are mutually exclusive attributes. If both are zero, the window width is determined by the length of the string it contains and the font used.
[CSG] Specifies whether or not soft returns in a multiline text box must be converted to hard returns. Possible values are:
TRUE Soft returns are converted to hard returns (default).
FALSE Soft returns are not converted to hard returns.
[CSG] Specifies whether or not users can edit the text string. Possible values are:
TRUE User can edit text string
(default).
FALSE User cannot edit text string.
[CG] Specifies how the TAB key is handled.
Possible values are:
DSNORMALEDITMODE
TAB generates a change focus event
(default).
DSTEXTEDITORMODE
TAB is inserted in the text.
[CSG] Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
[CSG] The contents of the text box. Use this attribute if the string length is greater than
4Kb. Otherwise, use DsNstring. The string must be null terminated.
Functions reference
51-36
DsNfontSet
(long)
DsNheight
(long)
DsNjustify
(long)
DsNmaxLength
(long)
DsNmultiLine
(boolean)
DsNobjectType
(long)
DsNoffset
(long)
DsNparent
(long)
User interface objects
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the object’s text. If this attribute is not set, the Windows default font is used.
[CSG] The height of the object, in pixels.
[CG] Specifies the alignment of text in a multiline window. The possible values are:
DSJUSTIFYLEFT (default)
DSJUSTIFYRIGHT
DSJUSTIFYCENTER
[CSG] Specifies the maximum length of the text string that a user can enter from the keyboard.
[CG] Specifies whether the text box supports multiple lines of text or only a single line.
Possible values are:
TRUE Multiline.
FALSE Single line (default).
DsNmultiLine and DsNpasswordField are mutually exclusive options.
[G] The object type.
[S]
[G]
The offset (position) in the text box where the data in DsNstring or
DsNfieldData is to be inserted. If this attribute is not specified, the new text overwrites the current text.
The ID of the parent object.
Functions reference
51-37
User interface objects
DsNpasswordField
(boolean)
DsNsetState
(long)
DsNsize
(long)
DsNstring
(string)
DsNtemplate
(long)
DsNtoolTip
(string)
DsNrows
(long)
DsNselectionArray
(long array)
[CG] Specifies a password-type text box. That is, characters entered in the text box are displayed as asterisks. DsNmultiLine and
DsNpasswordField are mutually exclusive options.
[CSG] The number of rows in a multiline text box. DsNheight and DsNrows are mutually exclusive attributes. If both are zero, the window height depends on the settings of the DsNfontSet, DsNstring, and DsNmultiLine attributes.
[CSG] The current position of the cursor or selection in the text box. The array contains two longs that represent the start and end position of the selection (zerobased index). When the two values are the same, this represents the position of the cursor.
[CS]
[G]
The state of the object. See
The length of the string in the text box, including the null character at the end of the string.
[CSG] The contents of the text box. The string can be a maximum of 4Kb. For long strings, use DsNfieldData instead.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The tooltip string associated with the text box. This is displayed when the user positions the mouse pointer over the window for one second or more. The string can be a maximum of 80 characters.
[CSG] The width of the object, in pixels.
DsNwidth
(long)
Functions reference
51-38
User interface objects
DsNwordWrap
(long)
DsNx
(long)
DsNy
(long)
[CG] Specifies whether word wrap is enabled or disabled in a multiline text box.
Possible values are:
TRUE Word wrap on (default).
FALSE Word wrap off.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCfontSet object defines a set of font attributes that other objects can apply to text strings. Objects indicate the font set to use by specifying the object ID of the font set in their DsNfontSet attribute.
Events
A DsCfontSet object does not generate events.
Attributes
DsNfsBaseline
(long)
DsNfsHeight
(long)
DsNfsMaWidth
(long)
[G]
[CG] The height of the font, in pixels. When creating a font object, the height includes the internal leading. When retrieving information about a font object, the height excludes the internal leading.
The default value is 12.
[G]
The height of the font (in pixels) relative to the baseline. This attribute corresponds to the MS
Windows Ascent attribute.
The maximum width of a (multibyte) character in pixels * 10. For nonproportional fonts, this attribute is identical to the DsNfsWidth attribute.
Functions reference
51-39
User interface objects
DsNfsPoints
(long)
DsNfsSlant
(long)
DsNfsSpacing
(long)
DsNfsTypeface
(string)
DsNfsWeight
(long)
DsNfsWidth
(long)
DsNobjectType
(long)
DsNparent
(long)
[G]
[G] The height of the font in pixels * 10. This is the same value as returned by DsNfsHeight * 10.
[CG] Possible values are:
FNTROMAN
FNTITALIC
[CG] The type of spacing. Possible values are:
FNTFIXED
FNTVARIABLE
Fixed spacing.
Proportional spacing.
[CG] The typeface name. For example, "Courier" or
"MS Sans Serif". The following values have a special meaning:
"DefaultFixed"
Use a predefined default font with fixed width character spacing.
"DefaultVariable"
Use a predefined default font with proportional character spacing.
If this attribute is not specified, or if it contains an empty string, BW uses the first font that matches the other specified attributes.
[CG] The weight of the font. Possible values are:
FNTMEDIUM
FNTBOLD
FNTNORMAL
[CG] The average width of the font in pixels * 10.
When neither DsNfsWidth nor DsNfsHeight are specified, the default is 8. When DsNfsWidth is not specified but DsNfsHeight is specified, the default width is DsNfsHeight/
π
.
[G] The object type.
The ID of the parent object.
Functions reference
51-40
User interface objects
DsNstring
(string)
DsNtemplate
(long)
[Q] Use this attribute in a query operation to retrieve the height and width of the specified text string as displayed using the font set. The reply message contains the DsNwidth and DsNheight attributes of the string.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Description
A DsCframe object places a three-dimensional border around a single child object.
Events
A DsCframe object does not generate events.
Attributes
DsNfontSet
(long)
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the title string defined by DsNstring.
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNsetState
(long)
[G]
[G]
[CS]
The object type.
The ID of the parent object.
The state of the object. See DsCmwindow.
Functions reference
51-41
User interface objects
DsNshadowType
(long)
DsNstring
(string)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CG] The frame’s border style. Possible values are:
DSSHADOWNONE
No shadowed border.
DSSHADOWIN
Frame appears inset.
DSSHADOWOUT
Frame appears outset (default).
DSSHADOWETCHEDIN
Frame uses the grouping border style.
DSSHADOWGROUPBOX
Frame uses the grouping border style – this frame style can display a title string (left aligned).
[CSG] The text string for the frame title. This is visible only when DsNshadowType is
DSSHADOWGROUPBOX.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG]
[CSG]
The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A graphical context object (DsCgc) defines a set of attributes that can be applied to graphical parts (that is, to subobjects of type DsCgpArc, DsCgpLine,
When multiple graphical parts have common attributes, you can define those attributes in a DsCgc object instead of specifying them individually for each graphical part. You can then apply the attributes to a graphical part by specifying the ID of the relevant DsCgc object in the DsNgc attribute of the graphical part.
Functions reference
51-42
User interface objects
Using this mechanism improves performance because less data needs to be transferred between the bshell and the user interface.
Events
A DsCgc object does not generate events.
Attributes
DsNgcBackground
(long)
DsNgcCapStyle
(long)
DsNgcFillColor
(long)
DsNgcFillStyle
(long)
DsNgcFontSet
[CSG] The rgb value that defines the background color of the graphical part.
[CSG] This controls the appearance of line ends.
Possible values are:
GCCAPBUTT
Lines are square at the endpoint.
GCCAPROUND
Lines are terminated by a circular arc whose diameter equals the line width.
[CSG] The rgb value that defines the fill color of the graphical part. This is relevant only to polygons, rectangles, and pies.
[CSG] The fill style for a graphical part. Possible values are:
GCFILLSOLID
GCFILL90
GCFILL75
GCFILL50
GCFILL25
GCFILL10
GCFILL00
GCFILLHOR
Fill solid.
Fill 90 %.
Fill 75 %.
Fill 50 %.
Fill 25 %.
Fill 10 %.
Fill 0 %.
Fill with horizontal lines.
GCFILLVER vertical lines.
GCFILLSLEFT
Fill with
Fill with slant left lines.
GCFILLSRIGHT Fill with slant right lines.
GCFILLHOLLOW Do not fill.
[CSG] The ID of a DsCfontSet object. The font
Functions reference
51-43
User interface objects
(long)
DsNgcForeground
(long)
DsNgcJoinStyle
(long)
DsNgcLineStyle
(long) object defines the font attributes to be applied to text in the graphical part.
[CSG] The rgb value that defines the foreground color of the graphical part.
[CSG] Defines how corners are drawn. Possible values are:
GCJOINMITER
The outer edges of the two lines extend to meet at an angle.
GCJOINROUND
Lines are joined by a circular arc whose diameter equals the line width and which is centered on the join point.
[CSG] The line and border style for a graphical part.
Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
DsNgcLineWidth
(long)
DsNgcTextStyle
(long)
DsNobjectType
(long)
[CSG] Defines the style of graphical text. Possible values are:
TSNORMAL
TSBOLD
Normal text
Bold text
TSREVERSE Reverse text
TSUNDERLINE Underlined text
TSFILLSOLID Fill background color
[G] The object type.
Functions reference
51-44
DsNparent
(long)
[G] The ID of the parent object.
User interface objects
Functions reference
51-45
User interface objects
DsNtemplate [CS] The ID of a template object that defines a set of attributes to be applied to the object.
Description
A graph is a rectangular child window that displays a graph. The DsCgraph object is not part of the standard BaanERP Tools object library. It is a third-party
OCX control. It can be controlled from 3GL scripts in the same way as standard objects. Several graphs can be displayed simultaneously within the same main window. A wide range of graph types is supported.
Events
A DsCgraph object can generate the following events:
EVTBUTTONPRESS
EVTBUTTONRELEASE
The parameters of these events are as described in “Event array parameters” in
Chapter 17, with the following exceptions: evt.button.x
evt.button.y
evt.button.rootx
evt.button.rooty
evt.button.state
The graph set selected.
The graph point selected.
The x-coordinate (Graphic Server units).
The y-coordinate (Graphic Server units).
0 when a graph set/point is selected
(Shift and Control states are not supported).
Functions reference
51-46
User interface objects
Attributes
DsNbackgroundColor
(long)
DsNbackgroundStyle
(long)
[CSG] The background color for the graphic object specified by the DsNbackgroundUse attribute.
Possible values are:
DSBLACK Black
DSBLUE Blue
DSGREEN Green
DSCYAN Cyan
DSRED Red
DSMAGENTA Magenta
DSBROWN Brown
DSLGRAY Light gray (default)
DSDGRAY
DSLBLUE
Dark gray
Light blue
DSLGREEN Light green
DSLCYAN Light cyan
DSLRED Light red
DSLMAGENTA Light magenta
DSYELLOW Yellow
DSWHITE White
DSAUTOCOLOR Automatic black or white
(whichever provides the greatest contrast)
[CSG] The background style for the graphic object specified by the DsNbackgroundUse attribute.
Possible values are:
DSBGSTYLENO No background
(default).
DSBGSTYLESHADOW Drop shadow.
DSBGSTYLERAISED Sculptured raised.
DSBGSTYLELOWERED Sculptured lowered.
Functions reference
51-47
User interface objects
DsNbackgroundUse
(long)
DsNbottomTitle
(string)
[CSG] Specifies the graphic object to which the
DsNbackgroundStyle and DsNbackgroundColor attributes apply. Possible values are:
DSBGENTIRE
DSBGGRAPHAXES
DSBGGRAPHTITLE
DSBGLEFTTITLE
DSBGRIGHTTITLE
Entire graph window (default).
Graph and axes.
Top title.
Left title.
Right title.
DSBGBOTTOMTITLE Bottom title.
DSBGLEGEND Legend.
[CSG] The text of the graph title positioned at the bottom of the graph window. This can be up to
80 characters long, and can include new-line characters. Use DsNbackgroundStyle and
DsNbackgroundUse to change the style of the title.
Functions reference
51-48
DsNdrawMode
(long)
DsNelevation
(long)
User interface objects
[CS] The drawing mode for the graph control.
Possible values are:
DSDRAWNOACTION
Graph not drawn – reset to SDRAWDEFAULT to display the graph.
DSDRAWCLEAR
Graph not drawn but background set to color specified by DsNbackground.
DSDRAWDEFAULT
Redraws the graph immediately (default).
DSDRAWBLIT
Graph built in background, then displayed all at once.
DSDRAWCOPY
Copies the graph image as a bitmap to the clipboard.
DSDRAWROTATE
Redraws the graph itself without recalculating scales and redrawing titles and legends (True3D graphs only).
DSDRAWUPDATE
Updates a time series graph with newly added points.
[CSG] The vertical viewing angle for true3D graphs.
The value can be any angle between -60 degrees and 90 degrees.
Functions reference
51-49
User interface objects
DsNextraData
(long array)
DsNforegroundColor
(long)
[CS] A two-dimensional array that holds additional data for a graph. You fill the array in the same way as you fill the DsNgraphData array. When referencing a single data point, use DsNthisSet and DsNthisPoint to index the data point.
Possible values are:
Pie charts
DSEDNORMAL Not exploded (default).
DSEDEXTRA Exploded.
Line, Lin/log, Log/lin, Log/log, Polar, Scatter
(2D), Tape
DSEDNORMAL Point shown (default).
DSEDEXTRA Point not shown.
Time series
DSEDNORMAL No statistical lines (default).
DSEDEXTRA Mean line.
DSEDSTDDEV Standard deviation line.
DSEDEXTRA and DSEDSTDDEV can be combined.
[CSG] The foreground color for the graphic object specified by the DsNforegroundUse attribute.
See DsNbackgroundColor for the list of possible values. The default is
DSAUTOCOLOR.
Functions reference
51-50
User interface objects
DsNforegroundUse
(long)
DsNgraphData
(long array)
DsNgraphStyle
(long)
[CSG] Specifies the graphic object to which the
DsNforegroundColor attribute applies. Possible values are:
DSFGRAPHTITLE
DSFGLEFTTITLE
DSFGRIGHTTITLE
DSFGBOTTOMTITLE
DSFGLABELS
DSFGLEGEND
DSFGAXES
DSFGGRIDS
DSFGMEAN
DSFGMINMAX
DSFGSTDDEV
DSFGBESTFIT
DSFGCURVE
DSFGDATALABELS
Top title (default)
Left title
Right title
Bottom title
Labels
Legend
Axes
Gridlines
Mean line
Min and max lines
Standard deviation lines
Best-fit line
Fitted curve
Data labels
[CS] A two-dimensional array that holds the actual data values for a graph. The array is indexed by
DsNthisSet and DsNthisPoint.
For a graph with two data sets and three data points per set, the array data is filled as follows: set1_pt1 + set1_pt2 + set1_pt3 + set2_pt1 + set2_pt2 + set2_pt3
[CSG] The graph style. This attribute is not relevant for
Bubble, Candlestick, Tape, and Time series graph types. Possible values are:
Functions reference
51-51
User interface objects
Area (2D/3D)
DSAREASTACKED
DSAREAABSOLUTE
Stacked (default).
Absolute.
DSAREAPERCENTAGE Stacked percentage.
Bar (2D/3D)
DSBARVERTICAL Vertical bars (default).
DSBARHORIZONTAL Horizontal bars.
DSBARSTACKED
DSBARPERCENT
Stacked.
Percentage.
DSBARZCLUSTERED Z-clustered (3D bar only).
DSBARFLOATING Stacked floating.
DSBARPARETO Pareto.
These values can be combined, as appropriate.
Box-whisker
DSBOXRAWSAMPLES Raw data, samples drawn
(default).
DSBOXRAWNOSAMPLES Raw data, no samples
drawn.
DSBOXPARAMETRIC Parametric data.
Gantt
DSGANTTADJACNTBARS Adjacent bars (default).
DSGANTTSPACEDBARS Spaced bars.
High-low-close and Open-high-low-close
DSHLCOPEN Open, high, low, and close
DSHLCNOCLOSE bars (default).
No open or close bars.
DSHLCNOHIGHLOW No high or low bars.
DSHLCNOBARS No bars.
Line, log/lin, lin/log, and log/log
DSLINEONLY Lines only.
DSLINESYMBOLS
DSLINESTICKS
Symbols.
Sticks between points and y
DSLINELINES origin.
Lines.
.
These values can be combined.
Functions reference
51-52
User interface objects
Pie (2D/3D)
DSPIELINES Lines join labels to graph (default).
DSPIENOLINES No label lines.
DSPIECOLORED Colored labels.
DSPIEPERCENT Percentage labels.
These values can be combined.
Polar
DSPOLARLINE
DSPOLARSYMBOLS
DSPOLARSTICKS
DSPOLARLINES
Lines only (default)
Symbols.
Sticks.
Lines.
These values can be combined.
Scatter (2D)
DSSCATTER
DSSCATTERCURVE
Symbols only (default).
Curve only.
DSSCATTERSYMBOLS Symbols only.
These values can be combined.
Scatter (3D)
DSSCATTER3DSYMBOLS Symbols only (default).
DSSCATTER3DSTICKS Symbols and vertical
sticks.
DSSCATTER3DLINES Symbols and lines
between points.
These values can be combined.
Surface
DSSURFACE Filled panels and boundary lines (default).
DSSURFACEBDYONLY Boundary lines only.
DSSURFACEPANONLY Filled panels only.
DSSURFACEBDYPANWALL Filled panels, boundary lines, side wall.
DSSURFACEBDYWALL Boundary lines, side wall.
DSSURFACEPANWALL Filled panels, side wall.
Functions reference
51-53
User interface objects
DsNgraphTitle
(string)
DsNgraphType
(long)
DsNgridLineStyle
(long)
[CSG] The text of the graph title positioned at the top of the graph window. This can be up to 80 characters long, and can include new-line characters. Use DsNbackgroundStyle and
DsNbackgroundUse to change the style of the title.
[CSG] The graph type. Possible values are:
DSNOGRAPH
DS2DPIE
DS3DPIE
DS2DBAR
DS3DBAR
DSGANTT
DSLINE
DSLIN-LOG
No graph
2D pie
3D pie
2D bar
3D bar (default)
Gantt
Line
Lin/log
DSLOG-LIN
DSLOG-LOG
DS2DAREA
DS3DAREA
Log/lin
Log/log
2D area
3D area
DS2DSCATTER 2D scatter
DSTRUE3DSCATTER True3D scatter
DSTRUE3DSURFACE True3D surface
DSHLC High-low-close
DSOHLC Open-high-lowclose
DSBUBBLE
DSTAPE
DSBOXWHISKER
DSCANDLESTICK
DSPOLAR
DSTIMESERIES
Bubble
Tape
Box-whisker
Candlestick
Polar
Time series
[CSG] The line style applied to gridlines specified by
DsNgridStyle. Possible values are:
DSGRIDSOLID
DSGRIDDASHED
Solid lines (default)
Dashed lines
DSGRIDDOTTED Dotted lines
DSGRIDDASHDOT Dash-dot lines
DSGRIDDASHDOTDOT Dash-dot-dot lines
DSGRIDNULL Null
Functions reference
51-54
DsNgridStyle
(long)
DsNheight
(long)
DsNlabels
(long)
DsNlabelEvery
(long)
DsNlabelStyle
(long)
User interface objects
[CSG] Enables/disables gridlines on a graph. Possible values are:
DSGRIDOFF
No gridlines (default).
DSGRIDHORIZONTAL
Y (horizontal) gridlines – concentric circles in polar graphs.
DSGRIDVERTICAL
X (vertical) gridlines – radial lines in polar graphs.
DSGRIDBOTH
Both horizontal and vertical gridlines.
[CSG] The height of the object, in pixels.
[CSG] Enables/disables graph labels. Possible values are:
DSDISABLE
DSENABLEBOTH
DSENABLEX
DSENABLEY
No labels.
Both X and Y labels (default).
X labels only.
Y labels only.
[CSG] The frequency of X axis labels. You can specify any frequency from 1 (every data point is labeled) to 1000 (every 1000th data point is labeled, starting with the first point).
[CSG] The orientation of X and Z axes labels. For horizontal bar graphs and gantt graphs, the label style applies to the Y axis rather than the X axis.
For other graph types, Y axis labels are always horizontal. Possible values are:
DSLABELHORIZONTAL
DSLABELVERTICAL
Horizontal
(default)
Vertical
Functions reference
51-55
User interface objects
DsNlabelText
(void)
DsNleftTitle
(string)
DsNleftTitleStyle
(long)
[CS] A one-dimensional array that holds the text for graph labels.
For graph types with X and Y axes, the labels apply to data points on the independent axis
(normally the X axis). For pie charts, the labels apply to each pie slice. The default labels are the numbers of the data points.
The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long. To label one particular data point, you can index DsNlabelText using
DsNthisPoint.
Use DsNyLabelText and DsNzLabelText to specify label text for the Y and Z axes of a graph.
[CSG] The text of the graph title positioned on the left side of the graph window. This can be up to 80 characters long, and can include new-line characters.
Use DsNbackgroundStyle and
DsNbackgroundUse to change the style of the title.
[CSG] The orientation of the graph title specified by
DsNleftTitle. Possible values are:
DSTITLENORMAL
Horizontal (default)
DSTITLEUP
Vertical (read from bottom to top).
DSTITLEDOWN
Vertical (read from top to bottom).
Functions reference
51-56
DsNlegendPos
(long)
DsNlegendSize
(long)
DsNlegendStyle
(long)
DsNlegendText
(long)
User interface objects
[CSG] The position of the legend in the graph window.
Possible values are:
DSLEGENDRIGHT Right
DSLEGENDTOPRIGHT Top right
DSLEGENDTOP
DSLEGENDTOPLEFT
Top
Top left
DSLEGENDLEFT
DSLEGENDBOTTOMLEFT
Left
Bottom left
DSLEGENDBOTTOM Bottom
DSLEGENDBOTTOMRIGHT Bottom right
DSLEGENDNO No legend
(default)
[CSG] Specifies the size of the gap between lines in the legend as a percentage of the maximum possible gap. This latter varies depending on the size of the graph window and the number of items in the legend. You can specify any value from 0% to 100% (default).
[CSG] Specifies the color for the legend text. Possible values are:
DSLEGENDFG
Legend text set by DsNforegroundColor.
DSLEGENDCOLOR
Legend text in same colors as legend markers.
[CS] A one-dimensional array that holds text for the graph legend.
For graph based on a single data set (pie, bubble, and single-set bar graphs), the legends apply to the individual data points. For other graph types, the legends apply to the data sets.
The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long.
Functions reference
51-57
User interface objects
DsNlineStats
(long)
DsNnumPoints
(long)
DsNnumSets
(long)
DsNobjectType
(long)
[CSG] Enables/disables statistical lines and curves.
Both lines and curves are available for line, 2D scatter, high-low-close, open-high-low-close, and box-whisker parametric graphs. Only curves are available for candlestick graphs.
Possible values are:
DSSTATNOLINES No statistical lines
(default).
DSSTATMEAN Mean (average) line.
DSSTATMINMAX Min/max line.
DSSTATSTDDEV Standard deviation line.
DSSTATBESTFIT Best-fit line.
DSSTATCURVE Curve line.
You can combine all the above values.
[CSG] The number of points in the data sets of a graph.
This can be any value between 1 and 6000, provided that the total number of points in a graph does not exceed 128000. That is:
DsNnumSets * DsNnumPoints <= 128000
[CSG] The number of data sets in the graph. For most graph types, DsNnumSets can be any value between 1 and 6000. The exceptions are:
Pie (2D/3D) 1 set
[G]
Gantt
Surface
HLC
OHLC
Candlestick
Box-whisker
>=2 sets
>=2 sets
3 sets
4 sets
4 sets
7 sets for parametric data (can be higher for raw data)
The total number of sets in any graph is limited to 128000. That is:
DsNnumSets * DsNnumPoints <= 128000
The object type.
Functions reference
51-58
User interface objects
DsNparent
(long)
DsNperspective
(long)
DsNrightTitle
(string)
DsNrightTitleStyle
(long)
DsNrotation
(long)
DsNsetState
(long)
DsNtemplate
(long)
[G] The ID of the parent object.
[CSG] The degree of perspective foreshortening for true3D graphs that use the perspective projection method. This represents the perceived distance from which the graph is viewed. The value must lie in the range 1 to 100
(default is 50).
[CSG] The text of the graph title positioned on the right side of the graph window. This can be up to 80 characters long, and can include new-line characters.
Use DsNbackgroundStyle and
DsNbackgroundUse to change the style of the title.
[CSG] The orientation of the graph title specified by
DsNrightTitle. Possible values are:
DSTITLENORMAL
Horizontal (default).
DSTITLEUP
Vertical (read from bottom to top).
DSTITLEDOWN
Vertical (read from top to bottom).
[CSG] The horizontal viewing angle for true3D graphs.
The value can be any angle between -180 degrees and 180 degrees.
[CS] The state of the object. See DsCmwindow.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-59
User interface objects
DsNthisPoint
(long)
DsNthisSet
(long)
DsNtickFrequency
(long)
[CS]
[CS]
This indexes array-based attributes by data point number. In combination with the DsNthisSet attribute, it indexes individual data points in a data set for direct access.
The following example modifies a pie graph, exploding points 3 and 5, and imploding point
4: long extra_array(10)
| Explode point extra_array(1) = DSEDEXTRA
| Return point to normal extra_array(2) = DSEDNORMAL
| Explode point extra_array(3) = DSEDEXTRA change.object( pie_graph_object,
DsNthisSet, 1, | Pie graph has only
| 1 set
DsNthisPoint, 3, | Start with point 3
DsNextraData, extra_array, 3 | Do for 3
| points
)
This indexes array-based attributes by data set number. In combination with the DsNthisPoint attribute, it indexes individual data points for direct access. DsNthisSet can be used to index the following attributes: DsNextraData,
DsNgraphData, DsNlegendText, and
DsNzLabelText.
The following example changes the value of one data point, using DsNthisSet and DsNthisPoint to index the data point: long data_array(100) data_array(1) = 50 change.object(graph_object,
DsNthisSet, 3,
DsNthisPoint, 6,
DsNgraphData, data_array, 1
)
[CSG] The frequency of ticks on the X axis (or on the
Y axis of horizontal bar graphs and gantt graphs). You can specify any frequency from 1
(every data point is labeled) to 1000 (every
1000th data point is labeled, starting with the first point).
Functions reference
51-60
DsNtickStyle
(long)
DsNtrue3D
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
DsNyLabelText
(void)
User interface objects
[CSG] Enables/disables tick marks on the graph axes.
Possible values are:
DSDISABLE
DSENABLEBOTH
DSENABLEX
DSENABLEY
No ticks
Both X and Y ticks
(default)
X ticks only
Y ticks only
[CSG] Enables/disables true3D graphing and sets the projection method. Possible values are:
DSTRUE3DOFF
No 3D (except for scatter and surface graphs).
DSTRUE3DPERSPECTIVE3D
Perspective projection (see DsNperspective).
DSTRUE3DISOMETRIC3D
Isometric projection.
DSTRUE3DOFF is the default when true3D is not available for the graph type.
DSTRUE3DPERSPECTIVE is the default when true3D is available for the graph type.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
[CS] A one-dimensional array that holds the text for
Y axis labels. The default labels indicate the numeric scaling of the axis. The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long.
Functions reference
51-61
User interface objects
DsNzLabelText
(void)
[CS] A one-dimensional array that holds the text for
Z axis labels in true3D graphs.
The default labels indicate the numeric scaling of the axis. However, no default labels are supplied for true 3D bar graphs, tape graphs, area graphs, or surface graphs. In these cases, you must set DsNzLabelText if you want to display z axis labels.
The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long. You can index
DsNlabelText using DsNthisPoint.
Description
A DsCgrid object is a rectangular child window that displays a spreadsheet grid.
Cells in the grid can contain not only data but also controls such as text boxes, list boxes, and check boxes.
Events
A DsCgrid object can generate the following events:
EVTCHANGEFOCUS
EVTGRIDEVENT
EVTKEYPRESS
EVTSETFOCUS
Functions reference
51-62
User interface objects
Attributes
DsNbackground
(long)
DsNcolHeader
(boolean)
DsNcolumn
(long)
DsNcolumns
(long)
DsNcolWidth
(long array)
[S]
[CG]
Specifies the background color (as an rgb value) for selected cells. The possible values are 0 to 16777215. When not specified, the background adopts the Windows standard.
Specifies whether or not the grid includes column headers. The default is TRUE.
[SQ] Use this to select a column in the grid. The value of the attribute is the column number
(0-based index). In combination with
DsNrow, this attribute selects an individual cell.
[CSG] The number of columns in the grid. The default is 1.
[CSQ] Use this to specify the width of the grid columns. You fill the array with the width values for each column, starting with the first column. If you specify only one value, all columns are set to that width.
If you first use DsNcolumn to select a column, the width specified is applied to the selected column. The width can be any value between 0 and 32768.
By default, all columns are the same width, the actual width depending on the width of the grid.
Functions reference
51-63
User interface objects
DsNcontrol
(long)
DsNeditable
(boolean)
DsNenum
(string)
DsNfontSet
(long)
DsNforeground
(long)
DsNfreezeColumns
(boolean)
[SQ]
[SQ]
[SQ]
[SQ]
[S]
[SG]
Use to create a control object in selected cell(s). Possible values are:
DSEDIT Edit control (text box)
(default).
DSSTATIC Static label field.
DSDDLISTBOX Drop-down list box.
DSCHECKBOX Check-box.
DSZOOMEDIT Zoom edit field.
For an edit control, use DsNmaxLength to specify the maximum number of input characters for the field.
For a drop-down list box, use DsNenum to specify the list box contents.
For a check box, use the values 1 and 0 to select/deselect the control.
For a drop-down list box, select the list box entry to be displayed by specifying its index number in the list.
Specifies whether or not an edit control is read-only. The default is FALSE.
Specifies the contents of a drop-down list box. Separate the individual list items using
\n. For example: item1\nitem2\nitem3\n
The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the entire grid or to selected cells. The default font is the Windows default font.
Specifies the text color (as an rgb value) for selected cells. The possible values are 0 to
16777215. When not specified, the Windows standard is used.
Use to freeze and unfreeze column(s) selected by the user. The default value is FALSE.
Functions reference
51-64
User interface objects
DsNgridEnableSelection
(long)
DsNgridFooter
(boolean)
DsNgridSetState
(long)
[CG] Specifies user selection options. Possible values are:
DSGRIDSELFULL All selection actions
(default).
DSGRIDSELNONE No selection actions.
DSGRIDSELROW Row selection.
DSGRIDSELCOL Column selection.
DSGRIDSELTABLE Grid selection.
DSGRIDSELCELL Cell selection.
DSGRIDSELMULTIPLE Multiple selections.
DSGRIDSELSHIFT Extend selection by pressing SHIFT.
DSGRIDSELKEYBOARD Selection with
SHIFT+Arrow
Key.
You can combine all the above values.
[CSG] Specifies whether or not the last row in the grid has a special style. In this special style, the font and top border are bold and the background color is that defined for 3D objects in the Windows standard color scheme.
[S] The state of a grid selection. Possible values are:
DSGRIDSTATEMARK
Mark the selection.
DSGRIDSTATEUNMARK
Unmark the selection.
DSGRIDSTATESETFOCUS
Set focus on the selection (single cell only).
DSGRIDSTATESETSENSITIVE
Make the selection sensitive.
DSGRIDSTATESETINSENSITIVE
Make the selection insensitive.
You cannot combine these values.
Functions reference
51-65
User interface objects
DsNgridType
(long)
DsNheight
(long)
DsNjustify
(long)
DsNmaxLength
(long)
DsNrange
(long array)
DsNrow
(long)
DsNrowHeader
(boolean)
[CG] The grid type. Possible options are:
DSGRIDTYPENORMAL
Normal grid functionality (default).
DSGRIDTYPEDISPLAY
Read-only functionality.
DSGRIDTYPEEDIT
Edit functionality.
DSGRIDTYPEVEERTEDIT
Vertical edit functionality.
[CSG] The height of the object, in pixels.
[SQ]
[SQ]
[SQ]
[SQ]
[CG]
Use this to specify the justification for data in selected cells. Possible values are:
DSJUSTIFYRIGHT
DSJUSTIFYLEFT (default)
DSJUSTIFYCENTER
The maximum number of input characters for an edit control field. This can be any value from 0 to 4096. 4096 is the default value.
Use this to select a range of cells. The array is filled as follows: start_row_num + start_col_num + end_row_num + end _col_num
Use this to select a row in the grid. The value of the attribute is the row number (0-based index). In combination with DsNcolumn, this attribute selects an individual cell.
Specifies whether or not the grid includes row headers. The default is TRUE.
Functions reference
51-66
DsNrowHeight
(long array)
DsNrows
(long)
DsNsetState
(long)
DsNstringArray
(void)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
User interface objects
[CSQ] Use this to specify the height of the grid rows.
You fill the array with the height values for each row, starting with the first row.
If you specify only one value, all rows are set to that height. If you first use DsNrow to select a row, the height specified is applied to the selected row.
The height can be any value between 0 and
32768. By default, all rows are the same height, the actual height depending on the font size.
[CSG] The number of rows in the grid. The default is
1 row.
[CS] The state of the object. See DsCmwindow.
[SQ]
[CS]
A one-dimensional array that holds data values for selected cell(s). When filling multiple cells, separate the data values with null characters. The data is filled from left to right and from top to bottom.
The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-67
User interface objects
Description
A graphical window (DsCgwindow) is a window in which applications can draw graphical parts such as lines, rectangles, polygons, and so on. Graphical windows also support user interface controls such as buttons, edit controls, list boxes, and so on.
Note that after changes to graphical parts, the graphical window in not redrawn until DsNsetState is set to DSUPDATE or until the window is repainted by the windows system.
Graphical windows support the following subobjects:
DsCgpArc
DsCgpComposite
DsCgpGroupBox
DsCgpHeader
DsCgpImage
DsCgpLine
DsCgpOleSite
DsCgpPie
DsCgpPolygon
DsCgpPolyline
DsCgpRectangle
DsCgpText
Events
A DsCgwindow can generate the following events:
EVTBUTTONPRESS
EVTBUTTONRELEASE
EVTBUTTONDPRESS
EVTBUTTONMOTION
EVTOLEEVENT
Functions reference
51-68
User interface objects
DsNgridColor
(long)
DsNgridHeight
(long)
DsNgridWidth
(long)
DsNgridX
(long)
DsNgridY
(long)
DsNheight
(long)
Attributes
DsNbackground
(long)
DsNborderColor
(long)
DsNborderWidth
(long)
DsNeventMask
(long)
DsNfirstSubObject
(long)
[CSG] The rgb value that defines the background color of the object. If this attribute is not specified, the object inherits the background color of its parent. If none of the parent objects specify a background color, the resource workAreaBackground is used.
[CSG] The rgb value that defines the color of the object’s border.
[CSG] The width of the object’s border, in pixels.
[CSG] Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
[SQ] The object ID of the subobject that is be drawn above all other subobjects. Setting this attribute changes the drawing order of subobjects.
[CSG] The color of the grid lines in the gwindow.
The default is black.
[CSG] The spacing (in pixels) between horizontal grid lines. If this is not specified, horizontal gridlines are not displayed.
[CSG] The spacing (in pixels) between vertical grid lines. If this is not specified, vertical gridlines are not displayed.
[CSG] The x-coordinate (in pixels) of the first grid line relative to the left border of the window. The default is 0.
[CSG] The y-coordinate (in pixels) of the first grid line relative to the top border of the window. The default is 0.
[CSG] The height of the object, in pixels.
Functions reference
51-69
User interface objects
DsNinferiorPointerCursor
(long)
DsNlastSubObject
(long)
DsNnextSubObject
(long)
[CSG] The shape of the inferior mouse pointer when positioned over the gwindow. A child of a gwindow inherits this mouse pointer, unless otherwise specified.
This attribute is overruled by a
DsNsuperiorPointerCursor attribute set for the window itself or for ancestor windows.
It is also overruled by a
DsNinferiorPointerCursor setting in descendant windows.
Possible values are:
DSCDEFAULT (default)
DSCARROW
DSCCROSSHAIR
DSCFLEUR
DSCHAND
DSCMAGNIFY
DSCAPPSTARTING
DSCPENCIL
DSCQUESTIONARROW
DSCSPLITHORIZONTAL
DSCSPLITVERTICAL
DSCSPRAYCAN
DSCWATCH
DSCNODROP
[SQ]
[SQ]
[G]
The object ID of the subobject that is be drawn beneath all other subobjects. Setting this attribute changes the drawing order of subobjects.
The object ID of the subobject that is drawn under the subobject specified by
DsNrefSubObject. Setting this attribute changes the drawing order of subobjects.
The object type.
DsNobjectType
(long)
DsNparent
(long)
[G] The ID of the parent object.
Functions reference
51-70
User interface objects
DsNprevSubObject
(long)
DsNrefSubObject
(long)
[SQ]
[SQ]
The object ID of the subobject that is drawn above the subobject specified by
DsNrefSubObject. Setting this attribute changes the drawing order of subobjects.
The object ID of the subobject used as a reference by DsNnextSubObject,
DsNprevSubObject, and DsNsequence.
The state of the object. See DsCmwindow.
DsNsetState
(long)
DsNsubObject
(long)
DsNsubObjectArray
(long array)
DsNsuperiorPointerCursor
(long)
[CS]
[Q]
[Q]
Use this attribute in a query operation to retrieve information about a subobject of the gwindow.
Use this attribute in a query operation to retrieve information about subobjects within a specified area of the gwindow.
[CSG] The shape of the superior mouse pointer when positioned over the gwindow. A child of a gwindow always inherits this mouse pointer.
This attribute overrules any
DsNinferiorPointerCursor attribute set for the window and all mouse pointers set for descendant windows. Possible values are:
DSCDEFAULT
DSCPENCIL
DSCARROW
DSCQUESTIONARROW
DSCCROSSHAIR
DSCSPLITHORIZONTAL
DSCFLEUR
DSCSPLITVERTICAL
DSCHAND
DSCSPRAYCAN
DSCMAGNIFY
DSCWATCH
DSCAPPSTARTING
DSCNODROP
Functions reference
51-71
User interface objects
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsClabel object provides a text string for labeling other objects.
Events
A DsClabel object does not generate events.
Attributes
DsNfontSet
(long)
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to label text The default font is the Windows default font.
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNjustify
(long)
DsNobjectType
(long)
[CSG] The alignment of the text string within the label object. Possible values are:
DSJUSTIFYLEFT (default)
DSJUSTIFYRIGHT
DSJUSTIFYCENTER
[G] The object type.
Functions reference
51-72
User interface objects
DsNparent
(long)
DsNsetState
(long)
DsNstring
(string)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[G]
[CS]
The ID of the parent object.
The state of the object. See DsCmwindow.
[CSG] The label string.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A main window (DsCmwindow) acts as the frame window for applications. It is used for starting processes and for creating graphical and character windows.
Typically, a main window contains a border, title bar, control menu box, sizing controls, menu bar, toolbar, status bar, work area, and scroll bars.
A main window also acts as the frame window for modal and modeless dialog boxes.
Events
A DsCmwindow object can generate the following events:
EVTKEYPRESS
EVTRESIZEWINDOW
Functions reference
51-73
User interface objects
Attributes
DsNbarMenu
(long)
DsNclose
(long)
DsNcmdStateList
(long array)
[CSG] The object ID of the DsCbarMenu object to be displayed across the top of a main window, below the title bar. The menu bar becomes visible after this attribute is set.
[CG] Specifies whether or not the menu of a dialog window includes the Close command. It also controls the processing of ALT+F4. The default is TRUE.
This attribute affects the window only if
DsNdialog=TRUE.
[S] Use to change the state of toolbar buttons and menu items. The array consists of one or more pairs of values. Each pair consists of the command ID of a toolbar button or menu item and the new state of the item. The possible values for the command state are:
DSCMDNORMAL
Resets the command/button to its default state.
DSCMDDISABLED
Disables the command/button.
DSCMDCHECKED
Sets the command/button to its checked state
(you can combine this with either of the other options).
Functions reference
51-74
User interface objects
DsNcommandStrings
(void data)
DsNdialog
(long)
DsNeventMask
(long)
[CS] The status field strings and tooltip strings for commands/buttons defined in DsCbarMenu and DsCtoolBar objects.
The DsNcommandStrings data consists of a header followed by multiple entries that specify the required strings.
The header contains two longs, one specifying the version number (currently always 1), the other specifying the number of following entries.
Each entry consists of a long and two strings.
The long contains the unique command ID.
The strings contain the status bar text and the tooltip text respectively.
[CG] Specifies whether or not the window is a dialog-type window. The default is FALSE.
This attribute is often used in combination with DsNmodal.
[CSG] Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNhelpButton
(boolean)
[CG]
DsNiconic
(long)
[C]
Use to specify whether or not a main window of dialog type (DsNdialog = TRUE) contains a help button in the title bar. This button provides context-sensitive help. The default is
TRUE.
Specifies whether or not the main window is realized as an icon (that is, minimized). The default is FALSE.
Functions reference
51-75
User interface objects
DsNinferiorPointerCursor
(long)
[CSG] The shape of the inferior mouse pointer when positioned over the main window. A child of a main window inherits this mouse pointer, unless otherwise specified.
This attribute is overruled by a
DsNsuperiorPointerCursor attribute set for the window itself or for ancestor windows. It is also overruled by a DsNinferiorPointerCursor setting in descendant windows. Possible values are:
DSCDEFAULT (default)
DSCPENCIL
DSCARROW
DSCQUESTIONARROW
DSCCROSSHAIR
DSCSPLITHORIZONTAL
DSCFLEUR
DSCSPLITVERTICAL
DSCHAND
DSCSPRAYCAN
DSCMAGNIFY
DSCWATCH
DSCAPPSTARTING
DSCNODROP
DsNmaxHeight
(long)
DsNmaxWidth
(long)
DsNminHeight
(long)
[CSG]
[CSG]
[CSG]
The maximum height (in pixels) of the main window.
The maximum width (in pixels) of the main window.
The minimum height (in pixels) of the main window.
DsNminWidth
(long)
[CSG] The minimum width (in pixels) of the main window.
Functions reference
51-76
User interface objects
DsNmodal
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNprocessGroup
(long)
DsNresizeable
(long)
DsNsetState
(long)
[CG]
[G]
[G]
This specifies whether the main window is modal or modeless. If TRUE, then the user must complete interaction with the window and close it before continuing with any further interaction outside the window. This attribute is normally used in combination with the
DsNdialog attribute. The default is FALSE.
The object type.
The ID of the parent object.
[CSG] The ID of the process group to which events from the main window are sent. See Chapter
31, Process groups.
[CG] Indicates whether or not the main window is resizable. The default is TRUE.
[CS] The state of the object. This can also be set with the corresponding functions. Possible values are:
DSMAP
Makes object visible (see map.object()).
DSUNMAP
Makes object invisible (see unmap.object()).
DSUPDATE
(Re)draws the object (see update.object()).
DSRAISE
Puts object in the forefront (see raise.object()).
DSLOWER
Puts object in the background (see also
DSCLEAR
Destroys the gparts on a gwindow.
DSSETSENSITIVE
Makes object sensitive – that is the object is enabled (see also set.sensitive()).
Functions reference
51-77
User interface objects
DsNstartHelpMode
(boolean)
DsNsuperiorPointerCursor
(long)
[S]
DSSETINSENSITIVE
Makes object insensitive – that is the object is disabled (see also set.sensitive()).
DSSETFOCUS
Sets keyboard input focus on the object (see
DSUNSETFOCUS
Moves keyboard input focus to the mwindow
(see unset.focus()).
Note that you cannot combine these values.
This indicates whether or not the window is in context-sensitive help mode (that is, whether or not SHIFT+F1 is enabled).
[CSG] The shape of the superior mouse pointer when positioned over the main window. A child of a main window always inherits this mouse pointer.
DsNsuperiorPointerCursor overrules any inferior mouse pointer
(DsNinferiorPointerCursor) set for the window and all mouse pointers set for descendant windows. Possible values are:
DSCDEFAULT
DSCPENCIL
DSCARROW
DSCQUESTIONARROW
DSCCROSSHAIR
DSCSPLITHORIZONTAL
DSCFLEUR
DSCSPLITVERTICAL
DSCHAND
DSCSPRAYCAN
DSCMAGNIFY
DSCWATCH
DSCAPPSTARTING
DSCNODROP
Functions reference
51-78
User interface objects
DsNtemplate
(long)
DsNtitle
(string)
[CS]
[CS]
The ID of a template object that defines a set of attributes to be applied to the object.
The title displayed in the title bar of the main window and as the caption for the window’s icon.
[CSG] The width of the object, in pixels.
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
The following attributes are supported for backward compatibility only. Do not use them in new applications.
DsNcolumns DsNdata
DsNmaxColumns DsNmaxRows
DsNmode DsNrows
DsNdisplay
DsNsize
DsNflags
DsNminRows DsNminColumns
DsNwindow
Description
array of pixels, with a specified width, height, and depth (number of planes), but no screen coordinates. A pixmap is a resource that is used by other objects that can display an image. Objects that can use a pixmap include DsCdrawnButton,
Events
A DsCpixmap object does not generate events.
Functions reference
51-79
User interface objects
Attributes
DsNbackground
Mode
(long)
DsNcolormap
(long)
DsNdata
(long array)
DsNdataType
(long)
[CS]
[CS]
Specifies the pixmap’s background mode.
Possible values are:
DSTRANSPARENT
DSOPAQUE (default)
The object ID of a DsCcolormap object. The color map defines an array of colors that the pixmap uses when DsNdataType is set to
DSPIXMAP8.
[CS]
[CS]
An array of indexes into the contents of a .gif file or into the color table of the DsCcolormap object specified by DsNcolormap.
The pixmap type. Possible values are:
DSPIXMAP8
DSPIXGIF8
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNtemplate
(long)
DsNwidth
(long)
[G]
[G]
[CS]
The object type.
The ID of the parent object.
The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
Functions reference
51-80
User interface objects
Description
A pushbutton, also referred to as a command button, represents an action that is carried out when the user selects the button. A pushbutton displays a text label.
A DsCdrawnButton object has the same functionality as a DsCpushButton object except that it displays a graphical image instead of a text label.
Events
A DsCpushButton object can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTBUTTONSELECT
Attributes
DsNeventMask
(long)
DsNfontSet
(long)
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the label on the pushbutton The default font is the
Windows default font.
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNreturnValue
(long)
[G]
[G]
[CSG]
The object type.
The ID of the parent object.
The value that is returned when the pushbutton is selected. The return value must be handled as an event. See Chapter 17, Events.
Functions reference
51-81
User interface objects
DsNsetState
(long)
DsNshowAsDefault
(long)
[CS] The state of the object. See DsCmwindow.
[CSG] Indicates whether of not the button is the default button. If TRUE, the button has a thicker border and can be activated with the ENTER key.
[CSG] The text string for the button’s label.
DsNstring
(string)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
DsNy
(long)
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-82
User interface objects
Description
A DsCradioBox object is an instance of DsCrowColumn object that contains radio buttons (also referred to as option buttons).
Events
A DsCradioBox object does not generate events.
Attributes
DsNfixedDimension
(long)
DsNheight
(long)
DsNnumColumns
(long)
DsNnumRows
(long)
DsNobjectType
(long)
[CSG] Specifies how children are arranged in the radio box. Possible values are:
DSVERTICAL
Children are arranged vertically, from top to bottom. Use DsNnumRows to specify the maximum number of children that can be displayed vertically.
DSHORIZONTAL
Children are arranged horizontally, from left to right. Use DsNnumColumns to specify the maximum number of children that can be displayed horizontally.
[CSG] The height of the object, in pixels.
[CSG]
[CSG]
[G]
The maximum number of children that the object can display horizontally.
The maximum number of children that the object can display vertically.
The object type.
Functions reference
51-83
User interface objects
DsNpacking
(long)
DsNparent
(long)
DsNsetState
(long)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CSG] The method of spacing the radio buttons within the radio box. Possible values are:
DSPACKTIGHT
The radio box contains cells of equal size, set to the size of the largest child window. Child windows positioned within these cells maintain their minimum dimensions. This is the default value.
DSPACKEQUAL
The radio box contains cells of equal size, set to the size of the largest child window. All child windows within these cells are displayed at the size of the largest child window.
DSPACKNONE
Child windows determine their own size and position. The radio box window is sized to accommodate all its children.
DSPACKSTACKED
All child windows have the same size and position. Only the last created child is visible.
All other children are stacked beneath this.
[G] The ID of the parent object.
[CS] The state of the object. See DsCmwindow.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-84
User interface objects
Description
A radio button (also referred to as an option button) represents a single option within a set of mutually exclusive options. It is either set or not set. Within a group of radio buttons, only one option in the group can be set. Selecting one radio button automatically deselects all others in the group. A partially filled in circle indicates the currently selected button. All radio buttons have an associated label.
Events
A DsCradioButton object can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTBUTTONSELECT
Attributes
DsNeventMask
(long)
DsNfontSet
(long)
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the radio button’s label. The default font is the
Windows default font.
[CSG] The height of the object, in pixels.
DsNheight
(long)
DsNjustify
(long)
[CSG] The alignment of the text string within the radio button window. Possible values are:
DSJUSTIFYLEFT (default)
DSJUSTIFYRIGHT
DSJUSTIFYCENTER
Functions reference
51-85
User interface objects
DsNobjectType
(long)
DsNparent
(long)
DsNset
(long)
DsNsetState
(long)
DsNstring
(string)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[G]
[G]
The object type.
The ID of the parent object.
[CSG] The state of the button (selected or unselected).
The default is FALSE.
[CS] The state of the object. See DsCmwindow.
[CSG] The string value for the radio button’s label.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-86
User interface objects
Description
A DsCrowColumn object is a container object that displays its children in rows and columns.
Events
A DsCrowColumn object does not generate events.
Attributes
DsNfixedDimension
(long)
[CSG] Specifies how children are arranged in the object. Possible values are:
DSVERTICAL
Children are arranged vertically, from top to bottom. Use DsNnumRows to specify the maximum number of children that can be displayed.
DSHORIZONTAL
Children are arranged horizontally, from left to right. Use DsNnumColumns to specify the maximum number of children that can be displayed.
DsNheight
(long)
DsNhspace
(long)
[CSG] The height of the object, in pixels.
[CSG] The horizontal spacing (in pixels) between child objects and between the edge of the
Functions reference
51-87
User interface objects
DsNinferiorPointerCursor
(long)
[CSG] The shape of the inferior mouse pointer when positioned over the object. A child of a
pointer, unless otherwise specified.
This attribute is overruled by a
DsNsuperiorPointerCursor attribute set for the object itself or for ancestor windows. It is also overruled by a DsNinferiorPointerCursor setting in descendant windows. Possible values are:
DSCDEFAULT (default)
DSCPENCIL
DSCARROW
DSCQUESTIONARROW
DSCCROSSHAIR
DSCSPLITHORIZONTAL
DSCFLEUR
DSCSPLITVERTICAL
DSCHAND
DSCSPRAYCAN
DSCMAGNIFY
DSCWATCH
DSCAPPSTARTING
DSCNODROP
DsNjustify
(long)
[CSG] The justification of child windows within the cells of the DsCrowColumn object. This is relevant only when DsNpacking is set to
DSPACKTIGHT.
The possible values for horizontal justification are:
DSJUSTIFY LEFT (default)
DSJUSTIFY CENTER
DSJUSTIFY RIGHT
The possible values for vertical justification are:
DSJUSTIFYTOP (default)
DSJUSTIFYMIDDEL
DSJUSTIFYBOTTOM
Functions reference
51-88
User interface objects
DsNnumColumns
(long)
DsNnumRows
(long)
DsNobjectType
(long)
DsNpacking
(long)
DsNparent
(long)
DsNsetState
(long)
When setting this attribute, you must combine a horizontal justification option and a vertical justification option.
[CSG] The maximum number of children that the object can display horizontally.
[CSG] The maximum number of children that the object can display vertically.
[G] The object type.
[CSG] The method of spacing the child objects within the DsCrowColumn object. Possible values are:
DSPACKTIGHT
The object contains cells of equal size, set to the size of the largest child window. Child windows positioned within these cells maintain their minimum dimensions. This is the default value.
DSPACKEQUAL
The object contains cells of equal size, set to the size of the largest child window. All child windows within these cells are displayed at the size of the largest child window.
DSPACKNONE
Child windows determine their own size and position. The DsCrowColumn window is sized to accommodate all its children.
DSPACKSTACKED
All child windows have the same size and position. Only the last created child is visible.
All other children are stacked beneath this.
[G] The ID of the parent object.
[CS] The state of the object. See DsCmwindow.
Functions reference
51-89
User interface objects
DsNsuperiorPointerCursor
(long)
DsNvspace
(long)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
[CSG] The shape of the superior mouse pointer when positioned over the object. A child of a
mouse pointer.
DsNsuperiorPointerCursor overrules any inferior mouse pointer
(DsNinferiorPointerCursor) set for the object and all mouse pointers set for descendant windows. Possible values are:
DSCDEFAULT
DSCPENCIL
DSCARROW
DSCQUESTIONARROW
DSCCROSSHAIR
DSCSPLITHORIZONTAL
DSCFLEUR
DSCSPLITVERTICAL
DSCHAND
DSCSPRAYCAN
DSCMAGNIFY
DSCWATCH
DSCAPPSTARTING
DSCNODROP
[CSG] The vertical spacing (in pixels) between child objects and between the and between the edge of the DsCrowColumn object and its nearest child.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
DsNy
(long)
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-90
User interface objects
Description
A DsCscrollWindow object provides a scrollable view of a child object. It supports a single child object only. Scroll bars enable users to view the data not currently visible in the window. Scroll bars are visible only when the child object is larger than the scroll window.
Events
A DsCscrollWindow object does not generate events.
Attributes
DsNchildPosX
(long)
DsNchildPosY
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNsetState
(long)
DsNtemplate
(long)
DsNwidth
(long)
[CSG] The distance (in pixels) from the left edge of the child object to the left edge of the scroll window.
[CSG] The distance (in pixels) from the top edge of the child object to the top edge of the scroll window.
[CSG] The height of the object, in pixels.
[G]
[G]
[CS]
The object type.
The ID of the parent object.
The state of the object. See DsCmwindow.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the object, in pixels.
Functions reference
51-91
User interface objects
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
Scroll bars enable users to scroll data that is too large to fit in the viewing window. They can be either horizontal or vertical. A scroll bar consists of the following components: n
A rectangular shaft (referred to as the scroll region). This represents the full amount of information available to the window.
n
A scroll arrow at either end of the scroll region. Clicking on these scrolls the data by specified increments.
n
A movable slider (also referred to as a scroll box). This indicates the relative position of the currently displayed data within the whole.
To scroll the data, users can click on one of the scroll arrows, click in the scroll region, or drag the slider.
Events
A DsCscrollbar object can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTSCROLLBARSELECT
Functions reference
51-92
User interface objects
Attributes
DsNeventMask
(long)
DsNincrement
(long)
DsNmaximum
(long)
DsNminimum
(long)
DsNparent
(long)
DsNsetState
(long)
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CSG] The amount the slider value changes when the user moves the slider by one increment.
Clicking on one of the scroll arrows moves the slider one increment towards the arrow. If a negative value is specified, the absolute value is used.
[CSG] The maximum value of the slider. This corresponds to the right or bottom position of the slider.
[CSG] The minimum value of the slider. This corresponds to the left or top position of the slider. DsNmaximum can be less than
DsNminimum.
[G] The object type.
DsNobjectType
(long)
DsNorientation
(long)
DsNpageIncrement
[CSG] The orientation of the scroll bar. Possible values are:
DSHORIZONTAL
DSVERTICAL (default)
[CSG] The amount the slider value changes when the user moves the slider by one page increment.
Clicking in the scroll region moves the slider one page increment in the direction of the click.
If a negative value is specified, the absolute value is used.
[G] The ID of the parent object.
[CS] The state of the object. See DsCmwindow.
Functions reference
51-93
User interface objects
DsNsize
(long)
DsNsliderValue
(long)
DsNtemplate
(long)
DsNx
(long)
DsNy
(long)
[CSG] The size of the scroll bar control, in pixels. This specifies the width of horizontal scroll bars and the height of vertical scroll bars. The default value is 100.
[CSG] The value corresponding to one side of the slider.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A slider object is used to set a value in a continuous range of values (for example, volume or brightness). It consists of a scroll bar that represents the full range of values and a movable slider whose position represents the current value.
It also includes labels that indicate the slider’s current, maximum, and minimum values. Tick marks are optional.
Events
A DsCslider object can generate the following events:
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTSCROLLBARSELECT
Functions reference
51-94
User interface objects
Attributes
DsNeventMask
(long)
DsNfontSet
(long)
DsNincrement
(long)
DsNmaximum
(long)
DsNminimum
(long)
DsNparent
(long)
DsNsetState
(long)
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the slider’s labels. The default font is the Windows default font.
[CSG] The amount the slider value changes when the user moves the slider by one increment.
[CSG] The maximum value of the slider. This corresponds to the right or bottom position of the slider.
[CSG] The minimum value of the slider. This corresponds to the left or top position of the slider.
DsNmaximum can be less than DsNminimum.
[G] The object type.
DsNobjectType
(long)
DsNorientation
(long)
DsNpageIncrement
[CSG] The orientation of the slider object. Possible values are:
DSHORIZONTAL
DSVERTICAL (default)
[CSG] The amount the slider value changes when the user moves the slider by one page increment. Clicking in the slider bar moves the slider one page increment in the direction of the click. If a negative value is specified, the absolute value is used.
[G] The ID of the parent object.
[CS] The state of the object. See DsCmwindow.
Functions reference
51-95
User interface objects
DsNsize
(long)
DsNsliderValue
(long)
DsNtemplate
(long)
DsNtickFrequency
(long)
DsNtickStyle
(long)
DsNx
(long)
DsNy
(long)
[CSG] The size of the slider in pixels. For horizontal sliders, it specifies the width of the slider. For vertical sliders, it specifies the height. The default value is 100.
[CSG] The value corresponding to one side of the slider.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The frequency of tick marks on the slider. This can be any interval from 0 to DsNmaximum -
DsNminimum. The default is 0. DsNtickStyle must not be DSNTICKNONE.
[CSG] The positioning of tick marks on the slider.
Possible values are:
DSTICKNONE
DSTICKTOP
No tick marks.
Tick marks above slider
(DSHORIZONTAL).
DSTICKBOTTOM Tick marks below slider
DSTICKRIGHT
DSTICKLEFT
(DSHORIZONTAL).
Tick marks to right of slider
(DSVERTICAL).
Tick marks to left of slider
DSTICKBOTH
(DSVERTICAL).
Tick marks on both sides of slider (default).
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-96
User interface objects
Description
A DsCstatusBar object provides a status bar that displays help and status information in a main window (DsCmwindow object). Each main window can include one DsCstatusBar object. The status bar is positioned at the bottom of the window. It occupies part of the client area of the window. When a status bar is added to a main window, the window size is adjusted so that the size of the client area is not affected.
The help and status messages are displayed in one or more panes in the status bar. There are three types of status bar panes: n
Default text pane. This displays the status field strings and tooltip strings for commands/buttons, as defined in the DsNcommandStrings attribute of the
occupied by other status panes.
n
The application can also write text to this pane using change.object().
Messages defined by the DsNcommandStrings attribute temporarily overwrite this text. But when these disappear, the last message sent to the default pane by the application is restored.
Application-defined text panes. The application supplies text for these panes using change.object(). The application must specify the length of the panes when creating the status bar.
n
Indicator panes. These indicate the current status of certain keyboard keys
(for example, NUM LOCK and CAPS LOCK). Microsoft Windows supplies the text for the panes. The application must specify the availability of the panes when creating the status bar.
Events
A DsCstatusBar object does not generate events.
Functions reference
51-97
User interface objects
Attributes
DsNobjectType
(long)
DsNparent
(long)
DsNsetState
(long)
DsNstatusIndicator
(long)
DsNstatusLength
(long array)
DsNstatusPane
(long)
DsNstatusText
DsNtemplate
(long)
[G]
[G]
The object type.
The ID of the parent object.
[CS] The state of the object. See DsCmwindow.
[CG] This specifies the indicators to be shown on the status bar. You can specify any combination of the following values:
DSCAPS
DSNUM
Caps Lock indicator.
Num Lock indicator.
DSSCRL Scroll Lock indicator.
DSKANA Kana Lock indicator (Japanese systems only).
Indicators are displayed on the status bar in the above order.
[C] Specifies the length (in characters) of applicationdefined text panes in the status bar. The number of entries in the array determines the number of application-defined panes displayed.
[SQ] This selects a status bar text pane for the
DsNstatusText attribute. The pane numbers range from 0 to the total number of panes defined by
DsNstatusLength. The default text pane is indexed by 0; this is also the default value.
[SQ] The text for the status bar text pane specified by
DsNstatusPane. If DsNstatusPane is not set, the text is displayed in the default text pane. To clear a text pane, set this attribute to an empty string.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-98
User interface objects
Description
A DsCtabFrame object provides a window with one or more form tabs. The tabs can be arranged in a single line or in multiple lines. When tabs are arranged on a single line, scroll buttons are added automatically if the window is not large enough to accommodate all the tabs.
A tab frame object can have multiple children. Children are automatically positioned at the top-left of the tab frame. The size of the tab frame window automatically adjusts to accommodate the largest child.
Events
A DsCtabFrame object can generate the following events:
EVTTABSELECT
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
Attributes
DsNeventMask
(long)
DsNfixedWidth
(boolean)
[CSG]
[CG]
Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
Specifies whether or not all tabs have the same width. The default is FALSE.
Functions reference
51-99
User interface objects
DsNfontSet
(long)
DsNheight
(long)
DsNmultiLine
(boolean)
DsNobjectType
(long)
DsNparent
(long)
DsNselected
(long)
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to tab titles. The default font is the Windows default font.
[CSG] The height (in pixels) of the client area of the tab frame window. If this is not specified, the height of the tab frame adjusts to accommodate the largest child window.
[CG]
[G]
Specifies whether or not the tabs are arranged on multiple lines. The default is FALSE.
The object type.
[G] The ID of the parent object.
[CSG] Use to select a particular tab by tab number. The tab numbers range from 1 to the total number of tabs. The default is 1.
[CS] The state of the object. See DsCmwindow.
DsNsetState
(long)
DsNstring
(string)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
[CSG] The text of the tab titles. Separate the text for each tab by \n. The number of title strings entered determines the number of form tabs displayed. This attribute is mandatory when creating a tab frame.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width (in pixels) of the client area of the tab frame window. If this is not specified, the width of the tab frame adjusts to accommodate the largest child window.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
Functions reference
51-100
User interface objects
DsNy
(long)
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCtemplate object defines a set of attributes that can be applied to other objects.
When multiple objects have common attributes, you can define those attributes in a template instead of specifying them individually for each object. You can then apply the attributes to an object by specifying the ID of the relevant template in the object’s DsNtemplate attribute. Using this mechanism improves performance because less data needs to be transferred between the bshell and the user interface.
Events
A DsCtemplate object does not generate events.
Attributes
. . .
[CS] A DsCtemplate object can include any of the attributes available for other objects.
Functions reference
51-101
User interface objects
Description
A DsCtoolBar object defines a toolbar for a main window (DsCmwindow). An application creates the entire toolbar with a single create.object() call.
Subsequently, it can use change.object() to add, remove, change, enable, and disable toolbar buttons.
Use the DsNcommandStrings attribute of the main window to specify status field and tooltip text for the toolbar buttons.
Events
A DsCtoolBar object can generate the following event:
EVTBUTTONSELECT
Attributes
DsNbutton
(long)
[SQ]
DsNbuttonState
(long)
[SQ]
Selects a particular toolbar button. The value specified is an index into the toolbar button list
(1 based index) – separators are not counted.
The state of the toolbar button identified by
DsNbutton. Possible values are:
DSTBBTNDISABLEDUNCHECKED
DSTBBTNDISABLEDCHECKED
(DSCHECK buttons only)
DSTBBTNENABLEDUNCHECKED
(default)
DSTBBTNENABLEDCHECKED
(DSCHECK buttons only)
Functions reference
51-102
User interface objects
DsNcommandList
(long array)
DsNdockable
(boolean)
DsNeventMask
(long)
DsNgravity
(long)
[C]
[CG]
The list of the command identifiers associated with the toolbar buttons. This attribute is mandatory when creating a toolbar. The command identifiers must be in the range 0 to
12287.
The number of entries in the DsNcommandList array must equal the number of entries in the
DsNimageList array (excluding separator entries). The event generated when a user clicks a toolbar button contains the command ID for the button.
Specifies whether a toolbar is dockable or fixed.
When this attribute is FALSE, the toolbar is fixed at the top of the main window immediately below the menu bar. When TRUE (default), the toolbar is dockable; DsNgravity specifies its initial position.
[CSG] Specifies the events that the object can generate.
See select.event.input() for a list of possible masks.
[CG] The initial position and state of a dockable toolbar. Possible values are:
DSTBTOP
Docked at top of main window (default).
DSTBBOTTOM
Docked at bottom of main window.
DSTBLEFT
Docked at left of main window.
DSTBRIGHT
Docked at right of main window.
DSTBFLOATING
Floating toolbar, initially centered in main window.
DSTBINVISIBLE
Toolbar not visible (not valid in
Functions reference
51-103
User interface objects
DsNheight
(long)
DsNimageList
(long array)
DsNobjectType
(long)
DsNparent
(long)
DsNsetState
(long)
DsNstateList
(long array)
DsNtemplate
(long)
DsNtitle
(string)
[CSG] The height of the object, in pixels.
[CSG] The list of DsCpixmap objects and separators that the toolbar displays. This is a mandatory attribute for create.object(). A toolbar separator is indicated by a value of -1. All toolbar images must have the same width and height. The recommended size is 16 pixels wide and 15 pixels high.
[G] The object type.
[G] The ID of the parent object.
[CS] The state of the object. See DsCmwindow.
[CS]
[CS]
[CS]
The state of the toolbar buttons. The array consists of one or more pairs of values. The first value in each pair is the button index (1-based index). The second value defines the state of the button. Possible state values are:
DSTBBTNDISABLEDUNCHECKED
DSTBBTNDISABLEDCHECKED
(DSCHECK buttons only).
DSTBBTNENABLEDUNCHECKED
(default).
DSTBBTNENABLEDCHECKED
(DSCHECK buttons only).
The ID of a template object that defines a set of attributes to be applied to the object.
The title of the window of a floating toolbar. The default is an empty string.
Functions reference
51-104
User interface objects
DsNtypeList
(long array)
[C] The button types. The array consists of one or more pairs of values. The first value in each pair is the button index (1-based index). The second value defines the button type. Possible values are:
DSNORMAL Normal pushbutton (default).
DSCHECK A two-state button.
[CSG] The width of the object, in pixels.
DsNwidth
(long)
Description
A DsCtree object defines a tree view control. Like any tree view control, it displays a list of items as an indented outline that reflects the hierarchical relationship between the items.
Items in a tree control have a parent-child relationship. They can be either nodes or leaves. Nodes represent category headings and can have leaves and other
Functions reference
51-105
User interface objects
nodes as children. Leaves do not have children. All items, except the root node, have one parent node; the root node is the highest node in the tree.
Each item in a tree control consists of an icon and a text label. If a node has children, it is preceded by a + or - button that enables the user to expand or collapse it respectively.
Each item has a unique ID. An item also has a parent ID; this is the ID of the item’s parent node. An item can also have a sibling ID; this is the ID of the item that appears immediately below it within the same parent node. The parent and sibling IDs of an item determine where the item is positioned within the tree structure.
You use the DsNtreeData attribute to define the type, label, ID, image, and parent or sibling ID of a tree control item. You also use DsNtreeData to change the properties of a tree control item, by calling change.object() and defining the new properties in the DsNtreeData attribute.
For example, you can reposition an item within the tree control by specifying a different parent or sibling for the item. You cannot, however, change the parent
ID of an item to 0 (because a tree control can have only one root node). Nor can you change an item’s parent ID to that of one of the item’s descendants or to the item's own ID. You can change a leaf to a node and vice versa – however, if you change a node to a leaf, all children of the node are automatically removed. You cannot change the unique ID of an item directly. To assign a new ID to an item, you must remove the item and then redefine it with the new ID. Note that when an item has been removed, you can reuse its ID for a new item.
Navigation
Users can use the mouse or keyboard keys to navigate through a tree control and to activate items.
Mouse actions
To move to an item with the mouse, click on the item. To activate an item, and to expand and collapse a node, double-click on it.
Functions reference
51-106
User interface objects
Keyboard actions
Move between items
A single item at a time
UP ARROW, DOWN ARROW
One scroll page at a time
Pg Up, Pg Dn
To first and last items
HOME, END
To move to next item whose label begins with a particular character
Press key correspoding to the character
Expand/collapse nodes
Activate a leaf
RIGHT ARROW, LEFT ARROW
ENTER
All the above mouse and keyboard actions generate an EVTTREESELECT event
(see Chapter 17, Events). Pressing any key other than those mentioned above generates an EVTKEYPRESS event.
Events
A DsCtree object can generate the following events:
EVTTREESELECT
EVTKEYPRESS
EVTCHANGEFOCUS
EVTSETFOCUS
EVTHELP
Functions reference
51-107
User interface objects
Attributes
DsNcommandList
(long array)
DsNeventMask
(long)
DsNeventReasonMask
(long)
[CS] Use this to set the state of tree control items and to remove tree items. The array contains one or more entries in the following format: long The ID of a tree node or leaf.
long The state of the specified node or leaf:
DSTREEEXPAND
Expands the node by one level.
DSTREECOLLAPSE
Collapses the node if it is expanded.
DSTREEREMOVE
Removes the item (if it is a node, all its children are also removed).
DSTREEEXPANDALL
Expands the node and all its children.
[CSG] Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
[CSG] The EVTTREESELECT event can be generated when a tree item is activated, expanded, collapsed, or selected. The
DsNeventReasonMask attribute specifies for which of these actions or reasons the event is generated. If a particular reason is not set in this attribute, then an event is not generated for that reason. Possible values are:
EVTTREEREASONACTIVATEMASK
EVTTREEREASONEXPANDMASK
EVTTREEREASONCOLLAPSEMASK
EVTTREEREASONSELECTMASK
Use the bitwise OR operator to combine some or all of these flags.
Functions reference
51-108
User interface objects
DsNheight
(long)
DsNmode
(long)
DsNobjectType
(long)
DsNparent
(long)
DsNselectedId
DsNsetState
(long)
DsNtemplate
(long)
DsNtreeData
[CSG] The height of the scroll view window, in pixels.
When the tree is longer than the window, a vertical scroll bar is automatically enabled.
[CSG] The tree mode. Possible values are:
DSOPENAGAIN
When reopening node, restore previous state.
DSOPENNONE
When reopening node, collapse all subnodes.
[G] The object type.
[G] The ID of the parent object.
[CSG] Specifies the ID of the currently selected tree item.
[CS] The state of the object. See DsCmwindow.
[CS]
[CS]
The ID of a template object that defines a set of attributes to be applied to the object.
This contains the tree data. The data consists of the following information:
– A header containing the following fields: long Version number (currently always 1).
long Number of image sets used by the long tree images.
Number of items in the tree.
– Zero or more entries specifying the image sets used by the tree items.
Normally, tree items of the same type use the same icon. This icon can have a different appearance in different situations – for example, when the item is selected, not selected, expanded, collapsed, and so on.
An image set is the set of such images for a particular type of item.
Functions reference
51-109
User interface objects
For example, on the contents page of a
Windows help file, the following icons represent a collapsed book and an expanded book respectively. The two icons represent the image set for book-type items.
An image set entry contains the following fields: short The image set ID.
long The ID of the image for items not selected and not expanded.
long The ID of the image for items selected but not expanded. If this is 0, the default is the ID of the image for images not selected and not expanded.
long this is 0,
The ID of the image for nodes expanded but not selected. If the default is the ID of the image for items not selected and not expanded.
This is relevant only to node items.
long is 0, the
The ID of the image for nodes selected and expanded. If this default is the ID of the image for items selected but not expanded.
This is relevant only to node items.
– Zero or more item entries containing the
Functions reference
51-110
User interface objects
following fields: byte The item type. Possible values are:
2
3
0
1 leaf node sibling leaf sibling node string The text for the item’s label. This is a null-terminated string.
short The ID of the item’s image set. This can be the ID of an image set specified by the current DsNtreeData attribute, or the ID of an image set specified by a previous DsNtreeData attribute.
short A unique item ID.
short The ID of the item’s parent or sibling.
If the item type is 0 or 1, the item is inserted as the last item under the specified parent item – the parent ID of the root item is always 0.
If the item type is 2 or 3 (that is, sibling), the item is inserted above the specified sibling item. The parent or sibling ID must be that of an existing tree item.
When changing the property of a tree item with
for that item in the DsNtreeData attribute. In
Functions reference
51-111
User interface objects
DsNwidth
(long)
DsNx
(long)
DsNy
(long) the case of a node, it is not necessary to redefine the node’s children.
[CSG] The width of the scroll view window, in pixels.
When the tree is wider than the window, a horizonotal scroll bar is automatically enabled.
[CSG] The x-coordinate of the object’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the object’s outer top edge, in pixels, relative to the inner top edge of its parent.
Functions reference
51-112
User interface objects
Examples
The following is an example of DsNtreeData data used to create a new tree control:
DsNtreeData header
1
2
9
DsNtreeData image set entries
Image set ID Image ID
(not selected, not expanded)
Image ID
(selected, not expanded)
ID_FOLDER_SET ID_FOLDER_1 0
Image ID
(not selected, expanded)
ID_FOLDER_2 0
Image ID
(selected, expanded)
ID_SESSION_SET ID_SESSION_1 ID_SESSION_2 0 0
DsNtreeData item entries
0
0
1
1
0
1
0
0
1
root leaf1 leaf2 node1 node2 leaf7 leaf8 leaf9 node4
ID_FOLDER_SET 1 0
ID_SESSION_SET 2 1
ID_SESSION_SET 6 1
ID_FOLDER_SET 86 1
ID_FOLDER_SET 87 1
ID_SESSION_SET 88 1
ID_SESSION_SET 43 1
ID_SESSION_SET 78 1
ID_FOLDER_SET 361 1
Functions reference
51-113
User interface objects
Description
A DsCgpArc object defines a circular or elliptical arc inside a rectangle. The center of the circle or ellipse is the center of the rectangle. The major and minor axes are specified by the width and height attributes respectively. The parent object is always a graphical window (DsCgwindow).
Events
A DsCgpArc object does not generate events.
Attributes
DsNangle
(long)
DsNattribute
(long)
DsNgc
(long)
DsNgcBackground
(long)
[CSG] Specifies the start of the arc relative to the threeo’clock radial from the center of the arc. Angles are specified in degrees (maximum 360 degrees).
Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the object.
[CSG] The rgb value that defines the background color of the subobject.
Functions reference
51-114
User interface objects
DsNgcCapStyle
(long)
DsNgcForeground
(long)
DsNgcLineStyle
(long)
[CSG] This controls the appearance of line ends.
Possible values are:
GCCAPBUTT
Lines are square at the end point.
GCCAPROUND
Lines are terminated by a circular arc whose diameter equals the line width.
[CSG] The rgb value that defines the foreground color of the subobject.
[CSG] The line and border style for the subobject.
Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
DsNgcLineWidth
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
[CSG]
[G]
[CS]
The height of the bounding rectangle, in pixels.
The object type.
The ID of the subobject used as a reference by
DsNsequence.
Functions reference
51-115
User interface objects
DsNrotation
(long)
[CSG] Specifies the angle of the arc relative to the
DsNangle value. Angles are specified in degrees
(maximum 360 degrees). Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
DsNsequence
(long)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CS] The position of the arc relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
[CS] The ID of a template object that contains a set of attributes to be applied to the object.
[CSG] The width of the bounding rectangle, in pixels.
[CSG] The x-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
[CSG] The y-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
Functions reference
51-116
User interface objects
Description
A DsCgpComposite subobject groups a number of graphical parts so that you can manipulate them as a single unit. The parent object is always a DsCgwindow object.
Events
A DsCgpComposite object does not generate events.
Attributes
DsNattribute
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[G] The height of the object, in pixels.
DsNheight
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
[G]
[CS]
[CS]
The object type.
The ID of the subobject used as a reference by
DsNsequence.
The position of the composite object relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
Functions reference
51-117
User interface objects
DsNsubObjectArray
(long array)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
[CSG] The IDs of the subobjects that the group contains. This attribute takes two values. The first contains the name of the subobject array, the last specifies the number of subobjects the group contains.
[CS]
[G]
The ID of a template object that defines a set of attributes to be applied to the subobject.
The width of the subobject, in pixels.
DsNy
(long)
[CSG] The x-coordinate of the subobject’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the subobject’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCgpGroupBox object defines a frame on the parent window. It can also display a text string at the top of the frame. The parent object is always a
Events
A DsCgpGroupBox object does not generate events.
Attributes
DsNattribute
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
Functions reference
51-118
User interface objects
DsNgcBackground
(long)
DsNgcFontSet
(long)
DsNgcForeground
(long)
DsNgc
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
[G] The rgb value that defines the background color of the graphical part.
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to title text.
[G]
[CS]
The rgb value that defines the foreground color of the graphical part.
The ID of a DsCgc object that contains a set of attributes to be applied to the object.
[CSG] The height of the frame, in pixels.
[G] The object type.
DsNstring
(string)
DsNtemplate
[CS]
[CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the composite object relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
[CSG] The text string to be displayed at the top of the groupbox.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-119
User interface objects
DsNgcTextStyle
(long)
[CSG] Defines the style of the text string displayed at the top of the groupbox. Possible values are:
TSNORMAL
TSBOLD
Normal text.
Bold text.
TSREVERSE Reverse text.
TSUNDERLINE Underlined text.
TSFILLSOLID Fill with background color.
[CSG] The width of the frame, in pixels.
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the subobject’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the subobject’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCgpHeader subobject defines a header line on the parent window. The line can include a centered title string. The parent window is always a DsCgwindow object.
Events
A DsCgpHeader object does not generate events.
Attributes
DsNattribute
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
Functions reference
51-120
User interface objects
DsNgcBackground
(long)
DsNgcFontSet
(long)
DsNgcForeground
(long)
DsNgc
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
[G]
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to subobject’s text string.
[G]
The rgb value that defines the background color of the graphical part.
[CS]
[G]
The rgb value that defines the foreground color of the graphical part.
The ID of a DsCgc object that contains a set of attributes to be applied to the object.
The height of the header line, in pixels.
[G] The subobject type.
DsNstring
(string)
DsNtemplate
[CS]
[CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the header subobject relative to the reference subobject. Possible values are:
GPMKFIRST part is drawn above all other parts
GPMKLAST part is drawn under all other parts
GPMKNEXT part is drawn under DsNrefSubObject
GPMKPREV part is drawn above DsNrefSubObject
[CSG] The text string to be displayed in the center of the header line.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-121
User interface objects
DsNgcTextStyle
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CSG] Defines the style of the text string displayed in the center of the header line. Possible values are:
TSNORMAL
TSBOLD normal text bold text
TSREVERSE reverse text
TSUNDERLINE underlined text
TSFILLSOLID fill with background color
[CSG] The width of the header line, in pixels.
[CSG] The x-coordinate of the subobject’s outer left edge, in pixels, relative to the inner left edge of its parent.
[CSG] The y-coordinate of the subobject’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCgpImage object defines a graphical image to be drawn in the parent window. It is linked to a DsCpixmap object, which defines an array of pixels, with a specified width, height, and depth (number of planes), but no screen coordinates. The parent window is always a DsCgwindow object.
Events
A DsCgpImage subobject does not generate events.
Functions reference
51-122
User interface objects
Attributes
DsNattribute
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNpixmap
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
DsNtemplate
DsNwidth
DsNx
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[G] The height of the image, in pixels.
[G]
[CS]
The subobject type.
The ID of the pixmap to be drawn.
[CS]
[CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the image relative to the reference subobject. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
The width of the image, in pixels.
[G]
[CSG] The x-coordinate of the subobject’s outer left edge, in pixels, relative to the inner left edge of its parent.
Functions reference
51-123
User interface objects
DsNy
(long)
[CSG] The y-coordinate of the subobject’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCgpLine subobject defines a line to be drawn between two specified points in the parent window. The parent window is always a DsCgwindow object.
Events
A DsCgpLine object does not generate events.
Attributes
DsNattribute
(long)
DsNgcBackground
(long)
DsNgcCapStyle
(long)
DsNgcForeground
(long)
DsNgc
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[CSG] The rgb value that defines the background color of the graphical part.
[CSG] This controls the appearance of line ends.
Possible values are:
GCCAPBUTT
Lines are square at the end point.
GCCAPROUND
Lines are terminated by a circular arc whose diameter equals the line width.
[CSG] The rgb value that defines the foreground color of the graphical part.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the subobject.
Functions reference
51-124
User interface objects
DsNgcLineStyle
(long)
[CSG] The line style for the subobject. Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
DsNgcLineWidth
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
[G]
[CS]
[CS]
The subobject type.
DsNtemplate [CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the line relative to the reference subobject. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-125
User interface objects
DsNxo, DsNxn,
DsNyo, DsNyn
(long)
[CSG] The line is drawn between two points in the parent window. The DsNxo and DsNyo attributes specify the x- and y-coordinates of the start point, relative to the upper-left corner of the parent window. The DsNxn and DsNyn attributes specify the x- and y-coordinates of the end point, relative to the upper-left corner of the parent window.
Description
A DsCgpOleSite subobject defines a rectangle that can embed an OLE object.
The parent window is always a DsCgwindow object.
Events
A DsCgpOleSite subobject does not generate events.
Attributes
DsNappName
(string)
DsNattribute
(long)
DsNdata
(void)
DsNdocName
(string)
DsNerror
(long)
[CS]
[CSG]
[CSGQ]
[CS]
[G]
The name of the application in which the OLE object is embedded.
The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
Specifies the binary data that contains the OLE object.
The name of the document in which the OLE object is embedded.
Specifies the error code returned when a
Functions reference
51-126
DsNformat
(long)
User interface objects
[CQ]
The format of the data in DsNdata. Possible values are:
DSFORMATNATIVE
Native object format defined by server application (default).
DSFORMATTEXT
ASCII text format.
DSFORMATBITMAP
Bitmap format.
DSFORMATMETAFILE
Metafile format.
DSFORMATDIB
Device independent bitmap format.
DSFORMATWAVE
Wave file format.
DSFORMATUNICODETEXT
Unicode text format.
DSFORMATENHANCEDMETAFILE
Enhanced metafile format.
DSFORMATRICHTEXT
RTF format.
DSFORMATEMBEDSOURCE
Embedded source format.
DSFORMATEMBEDDEDOBJECT
Embedded object format.
DSFORMATLINKSOURCE
Link source format.
DSFORMATOBJECTDESCRIPTOR
Object description format.
DSFORMATLINKSOURCEDESCRIPTOR
Link source description format.
DSFORMATOWNERLINK
Owner link format.
Functions reference
51-127
User interface objects
DsNheight
(long)
DsNname
(string)
DsNobjectType
(long)
DsNprogId
(string)
[CSG]
[CS]
[G]
[CS]
DsNrefSubObject
(long)
DsNsequence
(long)
[CS]
[CS]
DsNsize
(long)
DsNtemplate
DsNverb
(long)
DsNwidth
(long)
[GQ]
[CS]
[S]
[CSG]
DSFORMATFILENAME
File name format
.
The height of the object, in pixels.
The name of the local file that contains the OLE object.
The subobject type.
OLE objects are registered with a unique program identifier. This attribute specifies that
ID.
The ID of the subobject used as a reference by
DsNsequence.
The position of the object relative to the reference subobject. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject
The size of the data in DsNdata.
The ID of a template object that defines a set of attributes to be applied to the object.
The action to be performed on the OLE object.
The width of the subobject, in pixels.
Functions reference
51-128
User interface objects
DsNx
(long)
DsNy
(long)
[CSG]
[CSG]
The x-coordinate of the subobject’s outer left edge, in pixels, relative to the inner left edge of its parent.
The y-coordinate of the subobject’s outer top edge, in pixels, relative to the inner top edge of its parent.
Description
A DsCgpPie subobject defines a filled circular or elliptical arc, within a bounding rectangle. This subobject is similar to a DsCgpArc subobject, except that it is filled with a color and fill style. The parent object is always a graphical window (DsCgwindow).
Events
A DsCgpPie object does not generate events.
Attributes
DsNangle
(long)
DsNattribute
(long)
DsNgcBackground
(long)
[CSG] Specifies the start of the pie relative to the threeo’clock radial from the center of the pie. Angles are specified in degrees (maximum 360 degrees).
Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[CSG] The rgb value that defines the background color of the subobject.
Functions reference
51-129
User interface objects
DsNgcFillColor
(long)
DsNgcFillStyle
(long)
DsNgcForeground
(long)
DsNgc
(long)
DsNgcJoinStyle
(long)
[CSG] The rgb value that defines the fill color of the graphical part.
[CSG] The fill style for a graphical part. Possible values are:
GCFILLSOLID
GCFILL90
GCFILL75
GCFILL50
GCFILL25
GCFILL10
GCFILL00
GCFILLHOR
Fill solid.
Fill 90 %.
Fill 75 %.
Fill 50 %.
Fill 25 %.
Fill 10 %.
Fill 0 %.
Fill with horizontal lines.
GCFILLVER vertical lines.
GCFILLSLEFT
Fill with
Fill with slant left lines.
GCFILLSRIGHT Fill with slant right lines
GCFILLHOLLOW Do not fill.
[CSG] The rgb value that defines the foreground color of the graphical part.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the object.
[CSG] Defines how corners are drawn. Possible values are:
GCJOINMITER
The outer edges of the two lines extend to meet at an angle.
GCJOINROUND
Lines are joined by a circular arc whose diameter equals the line width and which is centered on the join point.
Functions reference
51-130
User interface objects
DsNgcLineStyle
(long)
[CSG] The line and border style for a graphical part.
Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
DsNgcLineWidth
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNrotation
(long)
[CSG]
[G]
[CS]
The height of the bounding rectangle, in pixels.
The object type.
The ID of the subobject used as a reference by
DsNsequence.
[CSG] Specifies the angle of the pie relative to the
DsNangle value. Angles are specified in degrees
(maximum 360 degrees). Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
Functions reference
51-131
User interface objects
DsNsequence
(long)
DsNtemplate
(long)
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CS] The position of the pie relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] The width of the bounding rectangle, in pixels.
[CSG] The x-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
[CSG] The y-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
Description
A DsCgpPolygon subobject defines a closed figure, bounded by three or more straight sides, which is drawn in the parent window. It is basically a polyline whose first and last points are joined. A polygon subobject can have a fill color and style. The parent window is always a DsCgwindow object.
Events
A DsCgpPolygon subobject does not generate events.
Functions reference
51-132
User interface objects
Attributes
DsNattribute
(long)
DsNgcBackground
(long)
DsNgcFillColor
(long)
DsNgcFillStyle
(long)
DsNgcForeground
(long)
DsNgc
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[CSG] The rgb value that defines the background color of the subobject.
[CSG] The rgb value that defines the fill color of the graphical part.
[CSG] The fill style for a graphical part. Possible values are:
GCFILLSOLID
GCFILL90
GCFILL75
GCFILL50
GCFILL25
GCFILL10
GCFILL00
GCFILLHOR
Fill solid.
Fill 90 %.
Fill 75 %.
Fill 50 %.
Fill 25 %.
Fill 10 %.
Fill 0 %.
Fill with horizontal lines.
GCFILLVER vertical lines.
GCFILLSLEFT
Fill with
Fill with slant left lines.
GCFILLSRIGHT Fill with slant right lines
GCFILLHOLLOW Do not fill.
[CSG] The rgb value that defines the foreground color of the graphical part.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the object.
Functions reference
51-133
User interface objects
DsNgcJoinStyle
(long)
DsNgcLineStyle
(long)
DsNgcLineWidth
(long)
DsNobjectType
(long)
DsNpointArray
(long array)
[CSG] Defines how corners are drawn. Possible values are:
GCJOINMITER
The outer edges of the two lines extend to meet at an angle.
GCJOINROUND
Lines are joined by a circular arc whose diameter equals the line width and which is centered on the join point.
[CSG] The line and border style for a graphical part.
Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
[G] The object type.
[CSG] The array containing the positions of the points.
The point array must be filled as follows: n n n n points(1,1) contains the x-coordinate of the first point points(1,2) contains the y-coordinate of the first point points(number of points,1) contains the xcoordinate of the last point points(number of points,2) contains the ycoordinate of the last point
All coordinates must be specified in pixels relative to the upper-left corner of the parent window.
Functions reference
51-134
User interface objects
DsNrefSubObject
(long)
DsNsequence
(long)
DsNtemplate
(long)
[CS]
[CS]
[CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the polygon relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
The ID of a template object that defines a set of attributes to be applied to the object.
Description
A DsCgpPolyline subobject defines a line to be drawn between a number of specified points in the parent window. The points are stored in the
DsNpointArray attribute. If the first and last points coincide, the lines are joined according to the setting of the DsNgcJoinStyle attribute. The parent window is always a DsCgwindow object.
Events
A DsCgpPolyline object does not generate events.
Functions reference
51-135
User interface objects
Attributes
DsNattribute
(long)
DsNgcBackground
(long)
DsNgcCapStyle
(long)
DsNgcForeground
(long)
DsNgc
(long)
DsNgcJoinStyle
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
[CSG] The rgb value that defines the background color of the subobject.
[CSG] This controls the appearance of line ends. Possible values are:
GCCAPBUTT
Lines are square at the endpoint.
GCCAPROUND
Lines are terminated by a circular arc whose diameter equals the line width
[CSG] The rgb value that defines the foreground color of the graphical part.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the object.
[CSG] Defines how corners are drawn. Possible values are:
GCJOINMITER
The outer edges of the two lines extend to meet at an angle.
GCJOINROUND
Lines are joined by a circular arc whose diameter equals the line width and which is centered on the join point.
Functions reference
51-136
User interface objects
DsNgcLineStyle
(long)
[CSG] The line and border style for a graphical part.
Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
DsNgcLineWidth
(long)
DsNobjectType
(long)
DsNpointArray
(long array)
[G] The subobject type.
DsNrefSubObject
(long)
[CSG] The array containing the positions of the points.
The point array must be filled as follows: n n n n points(1,1) contains the x-coordinate of the first point points(1,2) contains the y-coordinate of the first point points(number of points,1) contains the xcoordinate of the last point points(number of points,2) contains the ycoordinate of the last point
All coordinates must be specified in pixels relative to the upper-left corner of the parent window.
[CS] The ID of the subobject used as a reference by
DsNsequence.
Functions reference
51-137
User interface objects
DsNsequence
(long)
[CS]
[CS]
The position of the polyline object relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
The ID of a template object that defines a set of attributes to be applied to the object.
DsNtemplate
(long)
Description
A DsCgpRectangle subobject defines a rectangle within the parent window. The parent window is always a DsCgwindow object.
Events
A DsCgpRectangle subobject does not generate events.
Attributes
DsNattribute
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
DsNgcBackground
(long)
[CSG] The rgb value that defines the background color of the subobject.
DsNgcFillColor
(long)
[CSG] The rgb value that defines the fill color of the graphical part.
Functions reference
51-138
User interface objects
DsNgcFillStyle
(long)
DsNgcForeground
(long)
DsNgc
(long)
DsNgcJoinStyle
(long)
[CSG] The fill style for a graphical part. Possible values are:
GCFILLSOLID
GCFILL90
GCFILL75
GCFILL50
GCFILL25
GCFILL10
GCFILL00
GCFILLHOR
Fill solid.
Fill 90 %.
Fill 75 %.
Fill 50 %.
Fill 25 %.
Fill 10 %.
Fill 0 %.
Fill with horizontal lines.
GCFILLVER vertical lines.
GCFILLSLEFT
Fill with
Fill with slant left lines.
GCFILLSRIGHT Fill with slant right lines
GCFILLHOLLOW Do not fill.
[CSG] The rgb value that defines the foreground color of the graphical part.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the object.
[CSG] Defines how corners are drawn. Possible values are:
GCJOINMITER
The outer edges of the two lines extend to meet at an angle.
GCJOINROUND
Lines are joined by a circular arc whose diameter equals the line width and which is centered on the join point.
Functions reference
51-139
User interface objects
DsNgcLineStyle
(long)
DsNgcLineWidth
(long)
DsNheight
(long)
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
[CSG] The line and border style for a graphical part.
Possible values are:
GCLINESOLID
Normal line.
GCLINEDOUBLEDASH
Line stippled, using DsNgcForeground and
DsNgcBackground colors.
GCLINEONOFFDASH
Line stippled, using DsNgcForeground and the window’s background color.
[CSG] The width of lines and borders, in pixels.
[CSG] The height of the rectangle, in pixels.
[G] The subobject type.
[CS]
[CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the subobject relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn under DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
[CSG] The width of the rectangle, in pixels.
DsNwidth
(long)
DsNtemplate
(long)
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
Functions reference
51-140
User interface objects
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the upper-left corner of the rectangle, in pixels, relative to the upper-left corner of the parent window.
[CSG] The y-coordinate of the upper-left corner of the rectangle, in pixels, relative to the upper-left corner of the parent window.
Description
A DsCgpText subobject defines a text string to be drawn as a graphical part in the parent window. The parent window is always a DsCgwindow object.
Events
A DsCgpText subobject does not generate events.
Attributes
DsNattribute
(long)
[CSG] The status of the subobject. Possible values are:
GPNORMAL
Detectable and visible.
GPUNDETECTABLE
Cannot be detected with query.object().
GPINVISIBLE
Subobject is hidden.
DsNgcBackground
(long)
[CSG] The rgb value that defines the background color of the graphical part.
DsNgcFontSet
(long)
DsNgcForeground
(long)
DsNgc
(long)
DsNheight
(long)
[CSG] The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the text.
[CSG] The rgb value that defines the foreground color of the graphical part.
[CS] The ID of a DsCgc object that contains a set of attributes to be applied to the object.
[G] The height of the text string, in pixels.
Functions reference
51-141
User interface objects
DsNobjectType
(long)
DsNrefSubObject
(long)
DsNsequence
(long)
[G] The object type.
[CS]
[CS]
The ID of the subobject used as a reference by
DsNsequence.
The position of the text object relative to the reference object. Possible values are:
GPMKFIRST
Part is drawn above all other parts.
GPMKLAST
Part is drawn under all other parts.
GPMKNEXT
Part is drawn below DsNrefSubObject.
GPMKPREV
Part is drawn above DsNrefSubObject.
[CSG] The text string to display as graphical text.
DsNstring
(string)
DsNtemplate
DsNgcTextStyle
(long)
[CS] The ID of a template object that defines a set of attributes to be applied to the object.
[CSG] Defines the style of the graphical text. Possible values are:
TSNORMAL
TSBOLD
Normal text.
Bold text.
TSREVERSE Reverse text.
TSUNDERLINE Underlined text.
TSFILLSOLID Fill with background color.
[G] The width of the text string, in pixels.
DsNwidth
(long)
DsNx
(long)
DsNy
(long)
[CSG] The x-coordinate of the baseline starting position for the string, in pixels, relative to the upper-left corner of the parent window.
[CSG] The y-coordinate of the baseline starting position for the string, in pixels, relative to the upper-left corner of the parent window.
Functions reference
51-142
User interface objects
#define COMMAND.ABORT 10
#define COMMAND.EXIT 11
#define COMMAND.FIRST 20
#define COMMAND.LAST 21
#define COMMAND.PREV 22
#define COMMAND.NEXT 23 long toplevel, gwin, image, combox, combox_id function main()
{
image = 0
combox_id = 1
show.mwindow()
fill.work.area()
update.gwindow()
handle.event.loop()
} function long create.pulldown.menu(long mwin)
{
long barmenu, size
string menudata(1) based
alloc.mem(menudata, 3000)
size = 1
| write header info to buffer
store.long(1, menudata(size)) | version is 1
size = size + 4
store.long(8, menudata(size)) | menu contains 8 entries
size = size + 4
| create the File submenu
write.menu.entry(menudata, size, 1, 0, "&File", 0)
write.menu.entry(menudata, size, 2, COMMAND.ABORT, "Abort", 0)
write.menu.entry(menudata, size, 2, COMMAND.EXIT, "E&xit
| create the View submenu
write.menu.entry(menudata, size, 1, 0, "&View", 0)
write.menu.entry(menudata, size, 2, COMMAND.FIRST, "First", 0)
write.menu.entry(menudata, size, 2, COMMAND.LAST, "Last", 0)
write.menu.entry(menudata, size, 2, -1, "-", 0) | separator
write.menu.entry(menudata, size, 2, COMMAND.PREV, "Prev", 0)
write.menu.entry(menudata, size, 2, COMMAND.NEXT, "Next", 0)
barmenu = create.object(DsCbarMenu, mwin,
DsNmenuData, menudata, size-1,
DsNsetState, DSRAISE)
return(barmenu)
} function write.menu.entry(ref string menudata(), ref long size,
long level, long id, const string name(), long flags)
{
store.long(level, menudata(size))
Functions reference
51-143
User interface objects
size = size + 4
store.long(id, menudata(size))
size = size + 4
menudata(size) = name
size = size + len(name)
store.byte(0, menudata(size)) | terminate string with 0 char
size = size + 1
store.long(flags, menudata(size))
size = size + 4
} function show.mwindow()
{
long barmenu
toplevel = create.object( DsCmwindow, 0,
DsNtitle, "MWindow",
DsNprocessgroup, get.pgrp(pid),
DsNminWidth, 300,
DsNmaxWidth, 600,
DsNminHeight, 200,
DsNmaxHeight, 400)
barmenu = create.pulldown.menu(toplevel)
change.object( toplevel, DsNbarMenu, barmenu )
update.object(toplevel)
} function fill.work.area()
{
long rowcol
string listitems(300)
rowcol = create.object(DsCrowColumn, toplevel,
DsNvspace, 10,
DsNhspace, 10,
DsNnumColumns, 3,
DsNfixedDimension, DSHORIZONTAL )
create.object(DsClabel, rowcol,
DsNstring, "Article:" )
| 12345678901234567890123456789012345678901234567890
listitems= "article -1-printers-2-graph -3-books -4-logo-5"
store.byte(0, listitems(9))
store.byte(0, listitems(11))
store.byte(0, listitems(20))
store.byte(0, listitems(22))
store.byte(0, listitems(31))
store.byte(0, listitems(33))
store.byte(0, listitems(42))
store.byte(0, listitems(44))
store.byte(0, listitems(49))
combox = create.object(DsCdDComBox, rowcol,
DsNminWidth, 80,
DsNmaxWindowSize, 25,
DsNx, 80,
DsNy, 40,
DsNstringArray, listitems, 54)
gwin = create.object(DsCgwindow, rowcol,
DsNwidth, 100,
Functions reference
51-144
User interface objects
DsNheight, 100,
DsNpointerCursor, DSCHAND)
create.sub.object(gwin, DsCgpRectangle,
DsNx, 0,
DsNy, 0,
DsNwidth, 100,
DsNheight, 100 )
create.object(DsCpushButton, rowcol,
DsNstring, "Abort",
DsNreturnValue, COMMAND.ABORT)
create.object(DsCpushButton, rowcol,
DsNstring, "Exit",
DsNreturnValue, COMMAND.EXIT)
update.object(toplevel)
update.object(gwin)
} function update.gwindow()
{
string file(128)
string bufr(1) based
long buflen, fp, idp
change.object(combox, DsNselectedId, combox_id)
on case combox_id
case 1:
file = "${BSE}/gif/desktop.gif/tools1"
break
case 2:
file = "${BSE}/gif/desktop.gif/printer1"
break
case 3:
file = "${BSE}/gif/desktop.gif/graph1"
break
case 4:
file = "${BSE}/gif/desktop.gif/display1"
break
case 5:
file = "${BSE}/gif/desktop.gif/baanlogo"
break
default:
return
endcase
fp = seq.open(file, "r")
buflen = seq.seek(0, 2, fp)
alloc.mem(bufr, buflen)
seq.rewind(fp)
seq.read(bufr, buflen, fp)
seq.close(fp)
idp = create.object(DsCpixmap, 0,
DsNdata, bufr, buflen,
DsNdataType, DSPIXGIF8 )
if image <> 0 then
destroy.sub.object(gwin, image)
endif
image = create.sub.object(gwin, DsCgpImage,
DsNpixmap, idp,
Functions reference
51-145
User interface objects
update.object(gwin)
free.mem(bufr)
}
DsNx, 3,
DsNy, 3 ) function handle.event.loop()
{
long event(EVTMAXSIZE)
while TRUE
next.event(event)
on case evt.type(event)
case EVTMENUSELECT:
on case evt.menu.return(event)
case COMMAND.ABORT:
case COMMAND.EXIT:
return
case COMMAND.FIRST:
combox_id = 1
update.gwindow()
break
case COMMAND.LAST:
combox_id = 5
update.gwindow()
break
case COMMAND.PREV:
if combox_id > 1 then combox_id = combox_id - 1 update.gwindow()
endif
break
case COMMAND.NEXT:
if combox_id < 5 then combox_id = combox_id + 1
endif update.gwindow()
break
endcase
break
case EVTPUSHBUTTON:
if ( evt.button.return(event) = COMMAND.ABORT OR
evt.button.return(event) = COMMAND.EXIT ) then
return
endif
break
case EVTLISTBOXSELECT:
combox_id = evt.listbox.item_id(event)
update.gwindow()
break
default:
break
endcase
endwhile
}
Functions reference
51-146
The following is a list of the predefined variables available to programmers.
Variables specific to a particular function or group of functions are listed with those functions.
4 = 4GL only; R = Read-only
long actual.occ
string long long string string long long long string string long attr.adju(1) attr.bitset.mask
attr.changed
attr.conv(1) attr.currency$(3) attr.currkey
attr.dbase
attr.dbmaxlen
attr.deflt$(100) attr.descr$(60) attr.diga
4R Occurrence currently selected on form.
4 "l" align left
"r" align right
"c" align center
4 The available values for a bitset field
(see also enum functions).
4R Indicates if the current field has changed.
4 "u" convert to upper case
"l" convert to lower case
4R Current currency (see
4R Number of the current key. Or 0 if the current field is not a key field.
4R 1
0 current field is database field current field is not a database field
4R Maximum length of database field.
4R Default value of current field.
4 Description of current field.
4 Number of digits after decimal sign.
For strings, this is the maximum input length.
Functions reference
52-1
Predefined variables
long long string string long long long string string string string attr.digv
attr.divf
attr.domain$(16) attr.domm$(14) attr.dorp
attr.echo
attr.element
attr.enum.mask$(128) attr.format.
addition$(3) attr.helpfile$(10) attr.ille$(30)
4
4
Number of digits before decimal sign.
Division factor. (For entering numeric values without a decimal point.)
4R Domain of the current field.
4 Domain message code of current field.
4
1
0
Fill field with default or previous value: default previous
4
4
4
4
4
1
0 display value after input do not display value after input
This variable is supported for backward compatibility only. In preference, use the
Current array index (if field is an array element).
The values available for an enumerate field. Also the enumerate values available for the ask.enum() function.
See also set.enum.values.for.field() function.
Currency to be used for an amount format. Language to be used for a date format.
Help file of current field.
Illegal characters.
Functions reference
52-2
Predefined variables
long long long attr.imax
attr.inpfld
attr.input
string long long attr.lega$(30) attr.mandatory
attr.maxlen
string attr.message$(132) long long attr.minlen
attr.multioccur
string attr.nowait$(30) string attr.oformat$(30)
4 Maximum input length.
4R 0 display field
1 input field
2 input only
3 display only
4 0 input disabled
1 input enabled
This variable is supported for backward compatibility only. In preference, use disable.fields() and
4 Legal characters.
4R Mandatory input.
4
4
4R 1
0
Maximum display length of current field.
Message to be displayed when a field is filled after a before.input event.
Minimum length of current field.
multioccurrence field not multioccurrence field
4R Characters that start a field command. This variable is supported for backward compatibility only. In
BaanERP, field command functionality is replaced by form commands.
4 Output format of field.
Functions reference
52-3
Predefined variables
long string long string attr.permission
attr.previous$(30) attr.rang
attr.rang$(100) long string long attr.reallen
attr.refpath(100) attr.rndm
long attr.rotate
long string attr.sttp
attr.textfield$(17) string string attr.textkw1$(17) to attr.textkw4$(17) attr.textlang$(1) long attr.textmaxlines
4
4
4
4
4R Permissions for current field:
NO.PERMISSION
PERM.READ
PERM.MODIFY
PERM.WRITE
PERM.DELETE
NO.RESTRICTION
PERM.UNKNOWN
NO.PERM.DEFINED
See also db.permission() function.
16
30
32
64
4
8
1
2
4R Previous value of field.
4R Compiled expression ID for
4R Defines a range; values are automatically checked against this range.
4R Real database length of field.
4
4
4
4
Reference path.
Rounding method (see also round() function).
Current index in currency table (see
Start position in current field.
Name of the text field. Used by the
Text Manager.
Keywords of text. Used by the Text
Manager.
Language for text editing. Used by the Text Manager.
Maximum number of lines in the text editor. Used by the Text Manager.
Functions reference
52-4
Predefined variables
long string long string long long string string attr.textmode
attr.textopt$(25) attr.textstart
attr.textzoomsession$(18) attr.type
attr.zoomcode
attr.zoomreturn$(18) attr.zoomsession$(18)
4
4
1
3 display mode read/write mode
Used by the Text Manager.
Name of default option for editor window options. Used by the Text
Manager.
4 1
0
When new text is created, start text manager directly
(default).
When new text is created, fill keywords first.
Used by the Text Manager.
4 Session zoomed to by text editor zoom command. The default is
"Display Texts" session. Used by the
Text Manager.
4R Database type (DB.ENUM,
DB.STRING, DB.TIME, DB.DATE, and so on)
4
4
4
Field zoomcode. Possible values are:
0 (no zoom)
Z.SESSION
Z.MENU
Name of return field of zoom session on current field.
Session zoomed to from field.
Functions reference
52-5
Predefined variables
long long long long long string string string string long long string long string long auto.nextform
background before.update.check
break.view
chartgrp chm.name(128) chm.owner(14) chm.title(128) chm.user(14) choice curr.key
curr.pacc$(8) date date$(6) e
4 1 When modifying form data, automatically display next form when all occurrences on current form have been filled.
0 When modifying form data, do not automatically display next form when all occurrences on current form have been filled
(default).
It is not good GUI practice to use this variable.
R 1
0
4R 0
1 field is checked during input field is checked during update
Valid only in subsection check.input.
4 current session is modal current session is modeless
When searching for records in type 3 forms, break to next view when no records found and group fields match with old values.
Current chart group.
4
4
4
4
Name of the current chart.
Owner/creator of current chart.
Description of current chart.
Name of user of current chart.
4 Command ID of active command.
4R Current key number of main table.
R Current package combination.
R Number of days since 01-01-0001
(local time).
R Current system date (DDMMYY).
R Error code of last file action.
Functions reference
52-6
long error.bypass
long long long long long string exit.val$(80) string string long string long long fattr.currfld$(30) fattr.descr$(60) fattr.ftype
fattr.helpfile$(14) fattr.horizontal
fattr.init
fattr.nrtabs
fattr.occurnr
fattr.seqno
fattr.step
fattr.toplines
long fattr.total.line
string long string filename$(16) filled.occ
firstweek$(6)
Predefined variables
4 Indicates which database errors can be detected in your program script, see Chapter 11, Database operations, for a detailed description.
R String returned to the called program at the end of the process.
4R Name of current field.
4 Description of current form.
4R Type of current form (1, 2, 3, or 4).
4 Name of help file for current form.
4R True for horizontal occurrences.
4R Indicates if the form has been initialized.
4R Number of tabs on current form
(dynamic forms only).
4R Number of occurrences on current form.
4R Sequence number of current field in form.
4R Step size in horizontal grid.
4 The number of lines above the multioccurrence fields (default: 3).
Set in the before.program section.
4 If set in before.program section, this indicates that a total line must be displayed in the grid (see also
R Name of most-recently accessed table.
4R Number of filled occurrences.
R Date of the first day in the first week of the current year.
Functions reference
52-7
Predefined variables
long long long long long long long string long long string long string long form.curr
form.next
form.prev
graphical.mode
ignore.first.event
in.ret
initial.resize
job.device(14) job.device.requested
job.process
job.report(15) job.skip.date.question
language$(1) lattr.*
4R Current form number.
4R Next form number. -1 if no next form
4R Previous form number. -1if no previous form
4 Indicates whether the 3GL program runs in graphical mode (true) or in character mode (false). Default is false.
4 Indicates whether the start command of the current session must be skipped. The start command is defined in the session data.
4R Integer value of key pressed on input field. Cursor keys and zoom keys cannot be detected. Valid only in on.input, after.input, and after.field
sections.
4 Indicates automatic resize while starting a session.
Default device used by job process.
4
4 Indicates whether an output device must be specified when in job mode.
4R Indicates if process is started by a job.
4 Report code of report to be used when in job mode.
4 Indicates if the question "Consider the difference between entered date and system date?" must be skipped.
R Current language code.
See Chapter 4, Report scripts, in
U7168A US BaanERP Tools:
Programming Features.
Functions reference
52-8
string string long long long long long logname$(16) main.table$(9) mark.table() long long marked max.formtabs
double maxdouble long modify.prim.key
number.forms
parent pid previous.choice
Predefined variables
R Current login name.
4R Name of current main table.
4R This array indicates which records are marked. The size of this array is set to fattr.occurnr. For example, if records 3 and 8 are marked, then: mark.table(3) = 1 mark.table(8) = 1 and other elements in the array are 0
(false).
4R Indicates if there are marked records.
4 Defines the maximum number of form tabs to be displayed. Set in the before.program section.
R Maximum value of a double.
4 1
0
Primary key can be modified during modify. Set in programs of type 1, 2, and 3.
Primary key cannot be modified.
4R Number of forms within current session.
R Identification number of parent process.
R Identification number of current process.
4R Possible values:
0 add.set
dupl.occur
global.copy
modify.set
mark.delete
global.delete
Valid only in field sections and main.table.io.
Functions reference
52-9
Predefined variables
string string string prog.name$(16) query.extension(512) string long long string long long long long long long long procesinfo$(200) report$ reportgrp reportno sattr.descr$(80) select.only.fields.on.
form shell.type
spool.* start.by.wfc
stp.abort.error
stp.check.input.error
stp.skip.error
synchronized.reason
4
4
Information passed to program at startup.
R Name of current session.
4 A condition that is added to the
WHERE clause of a query to be parsed by the standard program
(using AND operator). Set in before.program section. In preference, use the query.extend
functions.
Current report code.
Current report group.
R Report number within group.
4R Description of the session.
true all reference tables are read
(default) false only reference tables of fields
on form are read
Use in before.program section.
R Exec_perm from user file.
See spool.open().
4R Session was started by workflow.
4R Boolean indicating if the function
4R Boolean indicating if the function
Valid only in check.input section.
4R Boolean indicating if the function
4R This indicates the command that started the dialog synchronization.
Functions reference
52-10
long string long string update.status
user.locale$(14) user.timer
user.type$(1) long string win.* zoomfield$(18) string zoomreturn$(18)
Predefined variables
4R 0
ADD.SET
no update during add
MODIFY.SET
during modify
MARK.DELETE
during delete
R Locale from user file.
R Timer from user file.
4R Current type of user. Possible values are:
S
N super user normal user
4R See get.window.attrs().
4R Variable set in the zoom session, indicating which field in the parent session was zoomed from.
4R Variable set in the zoom session, indicating which field’s value is to be returned. In the parent session, the variable attr.zoomreturn$ has the same value.
Functions reference
52-11
Predefined variables
Functions reference
52-12
A
abort() ...................................... 40-1 abort.io() .................................. 11-6 abort.transaction().................... 11-8 abs() ......................................... 25-2 acos() ....................................... 25-3 act.and.sleep().......................... 30-2 activate() .................................. 30-3 activate.search().............. 11-8, 11-9 add.view.field()........................ 19-3 alloc.mem().............................. 26-1 app_start().................................. 7-2 app_status() ............................... 7-3 appl.delete()............................... 1-3 appl.get.user() ............................ 1-3 appl.modify() ............................. 1-4 appl.set() .................................... 1-4 application locks overview ................................ 1-1 synopsis ................................. 1-2 argc() .............................. 30-3, 30-4 arguments (handling varying numbers of) overview .............................. 21-1 synopsis ............................... 21-1 argv$() ..................................... 30-4 array.info()............................... 26-3 asc() ........................................... 2-1
ASCII conversion overview ................................ 2-1 synopsis ................................. 2-1 asin()........................................ 25-3 ask.enum() ............................... 16-1 at.base() .......................... 48-1, 48-3 atan()........................................ 25-4 aud_close_audit() ...................... 3-5 aud_get_audit_dd().................... 3-5 aud_get_col_info()..................... 3-6 aud_get_fld_values() ................. 3-7 aud_get_hdr_size() .................... 3-9 aud_get_info_seq_hdr_size()..... 3-9 aud_open_audit() ..................... 3-10 aud_read_audit_rec() ............... 3-11 aud_read_info_hdr() ................ 3-12 aud_read_info_seq_hdr()......... 3-13 aud_read_next_audit_rec() ...... 3-14 aud_read_next_tran()............... 3-15 aud_read_seq_hdr() ................. 3-16 aud_read_tran()........................ 3-16 aud_select_host() ..................... 3-17 aud_update_infofile() .............. 3-19 aud_write_info_hdr()............... 3-20 aud_write_seq_hdr() ................ 3-21 audit information overview ................................ 3-1 synopsis ................................. 3-3
B
bc$()........................................... 6-3 bg$() .......................................... 6-3
Bit operations............................. 4-1 overview ................................ 4-1 synopsis ................................. 4-1 bit.and() ..................................... 4-1 bit.exor() .................................... 4-1 bit.in() ........................................ 4-1 bit.inv() ...................................... 4-1 bit.or()........................................ 4-1 bit.shiftl() ................................... 4-4 bit.shiftr()................................... 4-4 blank.all()................................. 19-3 blue.component()....................... 8-2 bms messages ................. 22-1, 22-3
Functions reference
53-1
Index
bms.add.mask()........................ 22-3 bms.delete.mask().................... 22-4 bms.receive$() ......................... 22-4 bms.receive.buffer() ................ 22-5 bms.send() ............................... 22-6 box() .......................................... 6-4 brp.close()................................ 34-1 brp.open() ................................ 34-2 brp.open.language() ................. 34-3 brp.ready() ............................... 34-4 bs$()........................................... 6-5 bse.dir$() ................................. 44-1 bse.release$() ........................... 44-2 bse.tmp.dir$() .......................... 44-2 bshell.pid()............................... 30-4 bucket messages ............. 22-2, 22-3
Business Chart Manager example................................ 5-37 glossary................................ 5-39 overview ................................ 5-1 synopsis ................................. 5-4
C
cf$() ........................................... 6-5 change.field.label() .................. 19-4 change.object() ........................ 51-5 change.progress.indicator() ..... 32-2 change.window() ....................... 6-7 changed() ................................. 49-1 character-based windows........... 6-1 overview ................................ 6-1 synopsis ................................. 6-1
Chart Manager5-1, 5-2, 5-3, 5-4, 5-
37, 5-38, 5-39, 5-40, 5-43 check.all.input()....................... 19-5 chm.axis.in() .............................. 5-7 chm.axis.out() ............................ 5-8 chm.chartman().......................... 5-9 chm.check() ............................. 5-10 chm.data.in()............................ 5-11 chm.data2domain.in().............. 5-12 chm.delete.data() ..................... 5-13
Functions reference
53-2
chm.delete.data2domains() ...... 5-13 chm.delete.footnotes() ............. 5-14 chm.delete.projections() .......... 5-14 chm.delete.sets() ...................... 5-15 chm.disconnect()...................... 5-15 chm.domain.in()....................... 5-16 chm.domain.out()..................... 5-17 chm.draw()............................... 5-18 chm.first.data.out() .................. 5-19 chm.first.data2domain.out()..... 5-20 chm.first.footnote.out()............ 5-20 chm.first.projection.out() ......... 5-21 chm.first.set.out()..................... 5-22 chm.footnote.in() ..................... 5-22 chm.get.request() ..................... 5-23 chm.new() ................................ 5-25 chm.next.data.out() .................. 5-25 chm.next.data2domain.out() .... 5-26 chm.next.footnote.out() ........... 5-27 chm.next.projection.out() ........ 5-28 chm.next.set.out() .................... 5-29 chm.open()............................... 5-29 chm.projection.in() .................. 5-30 chm.remove()........................... 5-31 chm.scale.axis() ....................... 5-31 chm.select() ............................. 5-33 chm.set.in() .............................. 5-34 chm.set.option() ....................... 5-35 chm.set.timer()......................... 5-35 chm.title.in() ............................ 5-36 chm.title.out() .......................... 5-36 choice.again() ................. 19-5, 19-6 choice.report() ......................... 34-5 choose.time.zone.from.list() .... 12-4 chr$() ......................................... 2-2 cl.screen() .................................. 6-7 clean.mess() ............................. 27-2 clear.query.extend.in.zoom() ... 39-3 client file access overview ................................ 7-1 synopsis ................................. 7-1 client2server()............................ 7-4
close.message()........................ 24-3 cmp.mem() .............................. 26-4 colors overview ................................ 8-1 synopsis ................................. 8-1 commit.transaction()................ 11-9 company operations overview ................................ 9-1 synopsis ................................. 9-1 compnr.check().......................... 9-1 compress.pixmap() .................. 51-6 concat$().................................. 41-2 copy.mem().............................. 26-5 cos() ......................................... 25-4 cosh() ....................................... 25-5 cp$() .......................................... 6-8 cr$() ........................................... 6-8 creat.tmp.file$() ....................... 13-3 create.extra.toolbar()................ 47-1 create.local.directory()............... 7-5 create.node() ............................ 42-4 create.object() .......................... 51-7 create.progress.indicator() ....... 32-1 create.sub.object().................... 51-8 create.sub.object.by.id()........... 51-9 create.tree().............................. 42-5 create.tree.button()................... 42-5 cs$() ........................................... 6-8 currency tables overview .............................. 10-1 synopsis ............................... 10-1 current.display()....................... 44-3 current.window() ....................... 6-9
D
d.expr() .................................... 18-1 dal.count.error.messages() ....... 27-2 dal.destroy()........................... 11-10 dal.get.error.message() ............ 27-3 dal.get.first.error.message() ..... 27-3 dal.new()................................ 11-12 dal.reset.error.messages() ........ 27-4
Index
dal.set.error.message() ............. 27-4 dal.set.property().................... 11-13 dal.start.business.method() .... 11-15 dal.update()............................ 11-17 data.input()................................. 6-9 database operations overview .............................. 11-1 synopsis ............................... 11-4 date.num()................................ 12-4 date.to.date() ............................ 12-5 date.to.inputstr$()..................... 12-6 date.to.num()............................ 12-7 date.to.utc().............................. 12-7 db.bind() ................................ 11-18 db.change.order()................... 11-19 db.check.restricted() .............. 11-20 db.check.row.changed()......... 11-21 db.check.row.domains()......... 11-21 db.clear.table() ....................... 11-22 db.columns.to.record()........... 11-24 db.create.table() ..................... 11-24 db.curr() ................................. 11-25 db.delete().............................. 11-26 db.drop.table() ....................... 11-26 db.eq().................................... 11-27 db.error()................................ 11-28 db.error.message() ................. 11-29 db.first() ................................. 11-29 db.ge().................................... 11-30 db.gt() .................................... 11-31 db.indexinfo() ........................ 11-32 db.insert()............................... 11-34 db.last().................................. 11-34 db.le() .................................... 11-35 db.lock.table()........................ 11-36 db.lt() ..................................... 11-37 db.next()................................. 11-37 db.nr.indices()........................ 11-38 db.nr.rows() ........................... 11-39 db.permission() ...................... 11-39 db.prev() ................................ 11-41 db.record.to.columns()........... 11-42
Functions reference
53-3
Index
db.ref.handle.mode() ............. 11-42 db.retry.hit()........................... 11-43 db.retry.point()....................... 11-44 db.row.length() ...................... 11-44 db.set.to.default()................... 11-45 db.unbind() ............................ 11-45 db.update()............................. 11-46 decompress.pixmap()............. 51-10 del.window()............................ 6-13 delch$().................................... 6-13 deleteln$()................................ 6-14 destroy.object()...................... 51-10 destroy.progress.indicator() ..... 32-3 destroy.sub.object() ............... 51-11 destroy.tree()............................ 42-6 dir.close()................................. 13-4 dir.entry()................................. 13-4 dir.open() ................................. 13-5 dir.open.tree() .......................... 13-6 dir.rewind().............................. 13-7 disable.commands()................. 19-6 disable.fields() ......................... 19-7 display()................................... 19-9 display.all().............................. 19-9 display.curr.occ()..................... 19-9 display.fld() .................. 19-9, 19-10 display.occ() ................. 19-9, 19-10 display.total.fields() ............... 19-11
DLL functions (executing) overview .............................. 14-1 synopsis ............................... 14-1 do.all.occ()............................. 19-12 do.occ().................................. 19-13 do.occ.without.update() ......... 19-14 double.cmp()............................ 25-5
DsCbarMenu............... 51-22, 51-25
DsCcheckBox ........................ 51-26
DsCcolorCell ......................... 51-28
DsCcolormap ......................... 51-29
DsCcomBox ....51-30, 51-32, 51-33
DsCdDComBox51-30, 51-32, 51-
33
Functions reference
53-4
DsCdDListBox ...................... 51-30
DsCdrawnButton ................... 51-34
DsCfield................................. 51-35
DsCfontSet ............................ 51-39
DsCframe............................... 51-41
DsCgc ......................... 51-42, 51-43
DsCgpArc ............................ 51-114
DsCgpComposite................. 51-117
DsCgpGroupBox ................. 51-118
DsCgpHeader ...................... 51-120
DsCgpImage ........................ 51-122
DsCgpLine........................... 51-124
DsCgpOleSite ...................... 51-126
DsCgpPie............................. 51-129
DsCgpPolygon..................... 51-132
DsCgpPolyline..................... 51-135
DsCgpRectangle .................. 51-138
DsCgpText........................... 51-141
DsCgraph ............................... 51-46
DsCgrid.................................. 51-62
DsCgwindow ......................... 51-68
DsClabel ................................ 51-72
DsClistBox51-30, 51-31, 51-32, 51-
33
DsCmwindow ........................ 51-73
DsCpixmap ............................ 51-79
DsCpushButton...................... 51-81
DsCradioBox ......................... 51-83
DsCradioButton ..................... 51-85
DsCrowColumn51-87, 51-88, 51-
89, 51-90
DsCscrollbar .......................... 51-92
DsCscrollWindow ................. 51-91
DsCslider ............................... 51-94
DsCstatusBar ......................... 51-97
DsCtabFrame ......................... 51-99
DsCtemplate ........................ 51-101
DsCtoolBar .......................... 51-102
DsCtree ................... 51-105, 51-107 dte$() ....................................... 12-8 dump.window()........................ 6-14 dynamic SQL queries
overview .............................. 15-1 synopsis ............................... 15-2
E
edit$() ...................................... 20-1 el$() ......................................... 6-14 enable.commands()................ 19-15 enable.fields() ........................ 19-16 end() ........................................ 40-2 enum.descr$() .......................... 16-3 enumerates overview .............................. 16-1 synopsis ............................... 16-1 error messages ......................... 27-1 es$() ......................................... 6-15 etol() ........................................ 16-4 events event array parameters....... 17-10 event types ........................... 17-7 overview .............................. 17-1 sample program ................. 17-20 synopsis ............................... 17-1 exec_dll_function().................. 14-1 exec_function()........................ 14-2 execute() ................................ 19-17 exit() ........................................ 40-2 exp() ........................................ 25-6 export() .................................... 50-7 expr.compile() ......................... 18-2 expr.free() ................................ 18-5 expressions (runtime) overview .............................. 18-1 synopsis ............................... 18-1
F
ff$().......................................... 6-15 fg$() ......................................... 6-16 file operations overview .............................. 13-1 synopsis ............................... 13-1 file.chmod() ............................. 13-7 file.chown() ............................. 13-9
Index
file.cp() .................................... 13-9 file.mv() ................................. 13-10 file.mv.across.hosts() ............. 13-10 file.rm().................................. 13-11 file.stat()................................. 13-11 first.window() .......................... 6-16 form field operations ............... 19-1 overview .............................. 19-1 synopsis ............................... 19-1 form.text$().............................. 27-5 format.round() ......................... 25-6 formatting input and output ..... 20-1 overview .............................. 20-1 synopsis ............................... 20-1 free.mem() ............................... 26-6 fs$() ......................................... 6-17 fstat.info() .............................. 13-12
G
get.arg.type()............................ 21-2 get.argc().................................. 21-2 get.col().................................... 6-17 get.company() ............................ 9-2 get.compnr() .............................. 9-2 get.cp()..................................... 6-17 get.display.data() ..................... 44-3 get.double.arg()........................ 21-3 get.field.label() ...................... 19-18 get.indexed.var()...................... 50-2 get.long.arg() ........................... 21-3 get.object()............................. 51-11 get.pgrp() ................................. 31-2 get.pixmap.info() ................... 51-12 get.row() .................................. 6-18 get.screen.defaults()............... 19-19 get.string.arg() ......................... 21-3 get.sub.object() ...................... 51-13 get.time.zone() ......................... 12-9 get.tree.default()....................... 42-7 get.tree.node.dpress()............... 42-7 get.tree.node.press()................. 42-8 get.tree.push.button() ............... 42-8
Functions reference
53-5
Index
get.var() ................................... 50-1 get.window.attrs().................... 6-18 get_function() .......................... 14-4 getcwd()................................. 13-14 getenv$().................................. 44-4 grab.mwindow() ...................... 31-2 green.component()..................... 8-2 group.exists() ........................... 44-5 group.invisible() .................... 19-20
H
hostname$() .................... 44-5, 44-6
I
import().................................... 50-6 inherit.object() ....................... 51-14 input.again() ............... 19-20, 19-21 input.to.utc() .......................... 12-11 inputfield.invisible() .............. 19-21 inputfield.password()............. 19-22 inputfield.visible() ................. 19-22 inputstr.to.date() ...................... 12-9 inputstr.to.utc() ...................... 12-10 insch$().................................... 6-19 insertln$() ................................ 6-19 int() .......................................... 25-7 interprocess communication
(bshell) overview .............................. 22-1 synopsis ............................... 22-3 interprocess communication (crossplatform) overview .............................. 23-1 synopsis ............................... 23-3 interprocess communication (OS level) overview .............................. 24-1 synopsis ............................... 24-2 is.administrator() ..................... 44-6 is.field.invisible()................... 19-23 isdigit() .................................... 41-3 isspace()................................... 41-4
Functions reference
53-6
K
keyin$().................................... 6-20 kill() ......................................... 30-5 kill.pgrp()................................. 31-3 kill.timer()................................ 46-1
L
l.expr() ..................................... 18-5 last.window() ........................... 6-21 len() ......................................... 41-4 len.in.bytes() ............................ 41-5 lf$() .......................................... 6-21 load.byte()................................ 41-6 load.double()............................ 41-6 load.float() ............................... 41-6 load.long() ............................... 41-6 load.short()............................... 41-6 load_dll() ................................. 14-4 local.to.utc()........................... 12-11 log() ......................................... 25-8 log10() ..................................... 25-8 lower.object()......................... 51-14 lpow() ...................................... 25-9 ltoe() ........................................ 16-5 lval() ........................................ 41-7
M
make.current()........................ 19-24 map.object()........................... 51-15 map.window().......................... 6-22 mark.handler() ......................... 6-22 mark.occ().............................. 19-24 mathematical operations overview .............................. 25-1 synopsis ............................... 25-1 max()........................................ 25-9 mb.cast$() ................................ 28-2 mb.cast.to.str$() ....................... 28-2 mb.char() ................................. 28-3 mb.char.info() .......................... 28-4 mb.display()............................. 28-4 mb.export$() ............................ 28-6
mb.ext.clean$() ........................ 28-6 mb.hasbidi()............................. 28-7 mb.import$()............................ 28-7 mb.isbidi() ............................... 28-8 mb.isbidi.language() ................ 28-9 mb.locale.info() ....................... 28-9 mb.localename$() .................. 28-10 mb.long.to.str$() .................... 28-10 mb.nsets() .............................. 28-11 mb.rev$() ............................... 28-11 mb.scrpos() ............................ 28-13 mb.set.info() .......................... 28-13 mb.strpos()............................. 28-14 mb.tss.clean$()....................... 28-15 mb.type() ............................... 28-15 mb.width() ............................. 28-16 memory operations overview .............................. 26-1 synopsis ............................... 26-1 mess() ...................................... 27-6 message handling overview .............................. 27-1 synopsis ............................... 27-1 message queues .............. 24-1, 24-2 message()................................. 27-7 min() ...................................... 25-10 mkdir()................................... 13-15 move.window()........................ 6-23 mtime() .................................... 46-2 multibyte strings overview .............................. 28-1 synopsis ............................... 28-1
N
new.window().......................... 6-23 next.event().............................. 17-2 no.scroll() ................................ 6-24 not.curr().................................. 49-2 not.fixed() ................................ 41-7 num.to.date$() ....................... 12-13 num.to.date() ......................... 12-12 num.to.week()........................ 12-13
Index
O
objects............................. 51-1, 51-3 objects and subobjects ............. 51-3 off.change.check() ................... 49-2 on.change.check() .................... 49-3 on.main.table()....................... 11-47 on.old.occ()............................ 19-25 open.message() ........................ 24-3 ostype() .................................... 44-7
P
parse_and_exec_function()...... 14-6 pathname() ............................. 13-15 pc$()......................................... 6-24 pcm.activate.session().............. 29-3 pcm.change() ........................... 29-4 pcm.change.object()................. 29-5 pcm.create() ............................. 29-5 pcm.create.object() .................. 29-8 pcm.destroy.object() ................ 29-9 pcm.get.data() ........................ 29-10 pcm.lock().............................. 29-11 pcm.refresh() ......................... 29-11 pcm.send.bms.event() ............ 29-12 peek.event() ............................. 17-3 pending.events() ...................... 17-4 pf$() ......................................... 6-25 pipe.clearerr() .......................... 24-5 pipe.close() .............................. 24-5 pipe.eof() ................................. 24-6 pipe.error()............................... 24-6 pipe.flush()............................... 24-7 pipe.gets() ................................ 24-8 pipe.open()............................... 24-8 pipe.puts()................................ 24-9 pipe.read().............................. 24-10 pipe.write() ............................ 24-11 pipes......................................... 24-2
Plan Chart Manager ........ 29-1, 29-2 example.............................. 29-23 objects..................... 29-15, 29-20 overview .............................. 29-1
Functions reference
53-7
Index
synopsis ............................... 29-3 pos()......................................... 41-8 pow() ..................................... 25-10 predefined variables................. 52-1 print.const() ........................... 19-26 process groups ......................... 31-1 overview .............................. 31-1 synopsis ............................... 31-1 processes.................................. 30-1 overview .............................. 30-1 synopsis ............................... 30-1 progress indicators overview .............................. 32-1 sample program ................... 32-4 synopsis ............................... 32-1 pstat()....................................... 30-5 put.double.arg() ....................... 21-3 put.indexed.var()...................... 50-5 put.long.arg() ........................... 21-3 put.string.arg() ......................... 21-3 put.var() ................................... 50-4
Q
qss.search() .............................. 37-1 qss.sort() .................................. 37-4 query extensions ............. 39-1, 39-2 synopsis ............................... 39-3 query.extend.from() ................. 39-5 query.extend.select()................ 39-4 query.extend.where() ............... 39-6 query.object() ........................ 51-15 query.sub.object() .................. 51-18
R
raise.object() .......................... 51-19 random number generators overview .............................. 33-1 synopsis ............................... 33-1 random() ......................... 33-1, 33-2 rdi.audit.hosts()........................ 36-4 rdi.column() ............................. 36-5 rdi.column.combined() ............ 36-6
Functions reference
53-8
rdi.date.input.format$()............ 36-7 rdi.domain() ............................. 36-8 rdi.domain.byte() ..................... 36-9 rdi.domain.combined() .......... 36-10 rdi.domain.date() ................... 36-10 rdi.domain.double() ............... 36-11 rdi.domain.enum() ................. 36-12 rdi.domain.enum.value()........ 36-12 rdi.domain.float()................... 36-13 rdi.domain.integer() ............... 36-14 rdi.domain.long() ................... 36-15 rdi.domain.set()...................... 36-15 rdi.domain.set.value() ............ 36-16 rdi.domain.string() ................. 36-17 rdi.domain.text() .................... 36-17 rdi.first.day.of.week() ............ 36-18 rdi.index() .............................. 36-19 rdi.reference() ........................ 36-20 rdi.table() ............................... 36-21 rdi.table.column() .................. 36-22 reactivate() ............................... 30-7 receive.bucket$() ..................... 22-8 recv.message() ....................... 24-11 red.component()......................... 8-2 refresh() ................................... 6-26 refresh.curr.occ() ................... 19-27 remove.local.directory() ............ 7-6 remove.local.file() ..................... 7-6 remove.mark() ....................... 19-28 reports overview .............................. 34-1 synopsis ............................... 34-1 resize.window() ....................... 6-26 resource sets............................. 35-1 overview .............................. 35-1 synopsis ............................... 35-1 restore.rcd.main()................... 11-48 rgb() ........................................... 8-2 rm.dir() .................................. 13-17 rnd.d() ...................................... 33-2 rnd.i() ....................................... 33-2 rnd.init()................................... 33-3
round() ................................... 25-11 rpos() ....................................... 41-8 rprt_close() .............................. 34-6 rprt_open()............................... 34-7 rprt_send() ............................... 34-8 rsc.boolean() ............................ 35-2 rsc.double().............................. 35-2 rsc.enum()................................ 35-2 rsc.font.spec() .......................... 35-2 rsc.get().................................... 35-3 rsc.long().................................. 35-2 rsc.put().................................... 35-4 rsc.setboolean()........................ 35-5 rsc.setdouble() ......................... 35-5 rsc.setenum() ........................... 35-5 rsc.setlong() ............................. 35-5 rsc.setstring() ........................... 35-5 rsc.string()................................ 35-2 run.baan.prog() ........................ 40-3 run.prog()................................. 40-3 runtime dictionary information overview .............................. 36-1 synopsis ............................... 36-1
S
s.expr$()................................... 18-6 scroll() ..................................... 6-27
Searching and sorting data....... 37-1 overview .............................. 37-1 synopsis ............................... 37-1 secondary toolbars overview .............................. 47-1 synopsis ............................... 47-1 select.event.input() .................. 17-4 send.bucket() ........................... 22-9 send.event() ............................. 17-6 send.message()....................... 24-12 send.wait() ............................... 22-9 seq.clearerr().......................... 13-17 seq.close().............................. 13-18 seq.close.local() ......................... 7-7 seq.eof()................................. 13-18
Index
seq.error() .............................. 13-19 seq.flush() .............................. 13-20 seq.fstat.local()........................... 7-7 seq.getc$() ............................. 13-20 seq.gets()................................ 13-21 seq.islocked()......................... 13-22 seq.lock() ............................... 13-23 seq.open() .............................. 13-24 seq.open.local().......................... 7-8 seq.putc$() ............................. 13-26 seq.puts() ............................... 13-27 seq.read() ............................... 13-27 seq.read.local() ........................ 7-10 seq.rewind() ........................... 13-28 seq.seek() ............................... 13-28 seq.tell() ................................. 13-29 seq.ungetc$() ......................... 13-29 seq.unlink() ............................ 13-30 seq.unlock() ........................... 13-30 seq.write() .............................. 13-31 seq.write.local() ....................... 7-10 server2client().......................... 7-11 set.alarm() ................................ 46-2 set.bg.color()............................ 6-27 set.currencies()......................... 10-1 set.enum.values() ..................... 16-5 set.enum.values.for.field() ....... 16-6 set.fg.color() ............................ 6-27 set.fields.default() ....... 19-28, 19-29 set.fmax()............................... 25-12 set.focus() .............................. 51-19 set.input.error() ........................ 27-9 set.limits.off() ........................ 11-49 set.max() ................................ 25-12 set.mem() ................................. 26-6 set.min()................................. 25-12 set.node.class()......................... 42-9 set.node.class.color() ............. 42-10 set.pgrp().................................. 31-3 set.sensitive() ......................... 51-20 set.strip.mode() ........................ 41-9 set.synchronized.dialog()......... 43-4
Functions reference
53-9
Index
set.time.zone() ....................... 12-15 set.timer() ................................ 46-3 set.transaction.readonly()....... 11-49 set.tree.background() ............. 42-11 set.tree.font().......................... 42-11 set.tree.foreground() .............. 42-12 set.tree.linewidth() ................. 42-13 set.tree.name() ....................... 42-14 setfmin() ................................ 25-12 sf$() ......................................... 6-28 shell()....................................... 40-4 shiftc$() ................................. 41-10 shiftl$() .................................. 41-10 shiftr$().................................. 41-10 signal()..................................... 30-7 sin()........................................ 25-13 sinh()...................................... 25-13 skip.io().................................. 11-50 sleep() ...................................... 30-8 sock.accept()................... 23-3, 23-4 sock.close().............................. 23-4 sock.connect().......................... 23-5 sock.flush() .............................. 23-7 sock.inherit()............................ 23-8 sock.listen() ............................. 23-9 sock.recv() .................. 23-10, 23-11 sock.send()............................. 23-11 sockets ..................................... 23-1 spool.buf() ............................... 38-2 spool.close() ............................ 38-2 spool.line()............................... 38-3 spool.open()............................. 38-3 spooling overview .............................. 38-1 synopsis ............................... 38-1 sprintf$().................................. 20-4
SQL query extensions overview .............................. 39-1 sample program ................... 39-7 sql.break()................................ 15-2 sql.close() ................................ 15-3 sql.exec() ................................. 15-3
Functions reference
53-10
sql.fetch()................................. 15-4 sql.parse() ................................ 15-4 sql.select.bind()........................ 15-5 sql.set.rds.full() ........................ 15-6 sql.where.bind() ....................... 15-7 sqrt() ...................................... 25-14 srand()...................................... 33-3 start.session() ........................... 40-7 start.synchronized.child() ........ 43-5 start.synchronized.child.with() 43-6 stat.info() ............................... 13-32 status messages ........................ 27-1 status.del() ............................. 27-10 status.field() ........................... 27-10 status.mess() .......................... 27-11 status.off().............................. 27-11 status.on() .............................. 27-12 stop()........................................ 40-8 stop.synchronized.child()......... 43-7 stopping programs and sessions40-1 overview .............................. 40-1 synopsis ............................... 40-1 store.byte()............................. 41-11 store.double()......................... 41-11 store.float() ............................ 41-11 store.long()............................. 41-11 store.occ.max() ........... 11-51, 11-52 store.occ.min() ............ 11-51, 11-52 stp.reset.value()...................... 19-29 str$() ...................................... 41-11 string operations overview .............................. 41-1 synopsis ............................... 41-1 string.scan() ........................... 20-10 string.set$() ............................ 41-12 strip$() ................................... 41-12
Structure Chart Manager. 42-1, 42-2 overview .............................. 42-1 synopsis ............................... 42-2 sub.window() ........................... 6-28 suspend().................................. 30-8 switch.to.company() .................. 9-3
synchronize.with.child() .......... 43-7 synchronized sessions overview .............................. 43-1 sample program ................... 43-8 synopsis ............................... 43-4
T
tab$() ....................................... 6-29 table.round() ............... 25-14, 25-15 tan() ....................................... 25-15 tanh() ..................................... 25-16 text fields ................................. 45-1 overview .............................. 45-1 synopsis ............................... 45-2 text.copy()................................ 45-3 text.copy.between.companies() 45-4 text.copy.language() ................ 45-5 text.defaults()........................... 45-6 text.delete().............................. 45-7 text.edit() ................................. 45-7 text.present.in.language() ........ 45-8 text.read() ................................ 45-9 text.rewrite() .......................... 45-10 text.to.buf() ............................ 45-11 text.window()......................... 45-12 text.write() ............................. 45-13 time zone functions overview .............................. 12-1 synopsis ............................... 12-2 time.num() ............................. 12-15 timers overview .............................. 46-1 synopsis ............................... 46-1 timezone.exists().................... 12-16 to.field()................................. 19-29 to.form() ..................... 19-30, 19-31 to.group()............................... 19-31 to.key() .................................. 11-52 tolower$() .............................. 41-13 toupper$() .............................. 41-13 tree structures........................... 42-1 tt.align.according.domain().... 41-13
Index
tt.bobject.desc() ..................... 36-23 tt.chm.appl.desc() .................. 36-23 tt.chm.application()................ 36-24 tt.chm.chart() ......................... 36-25 tt.chm.charttype()................... 36-25 tt.company()........................... 36-26 tt.currency() ........................... 36-27 tt.device()............................... 36-28 tt.field.desc().......................... 36-29 tt.index.desc() ........................ 36-29 tt.language()........................... 36-30 tt.library()............................... 36-30 tt.menu.desc() ........................ 36-31 tt.menu.present().................... 36-32 tt.report.desc()........................ 36-32 tt.reportgroup.exists() ............ 36-33 tt.session.desc()...................... 36-33 tt.session.permission() ........... 36-34 tt.session.present() ................. 36-34 tt.short.field.desc()................. 36-35 tt.table.desc() ......................... 36-35 tt.user()................................... 36-36
U
unmap.object()....................... 51-20 unmap.window()...................... 6-29 unset.focus() .......................... 51-21 update.object() ....................... 51-21 update.occ() ................ 19-32, 19-33 user information overview .............................. 44-1 synopsis ............................... 44-1 user interface objects overview .............................. 51-1 synopsis ............................... 51-2 user.exists().............................. 44-7 utc.num() ............................... 12-16 utc.to.date()............................ 12-17 utc.to.input() .......................... 12-17 utc.to.inputstr$() .................... 12-18 utc.to.local()........................... 12-19 utc.to.week() .......................... 12-19
Functions reference
53-11
Index
V
val() ......................................... 41-7 variables (based) overview .............................. 48-1 synopsis ............................... 48-1 variables (checking changes) overview .............................. 49-1 synopsis ............................... 49-1 variables (inter-process transfer) overview .............................. 50-1 synopsis ............................... 50-1 view.tree().............................. 42-15 vsprintf$() .............................. 20-12
W
wait()........................................ 30-9 wait.and.activate() ................. 30-10 week.to.num()........................ 12-21 week.to.utc() .......................... 12-21 with.object.set.do() ................ 11-53 with.old.object.values.do() .... 11-54 wrebuild() ................................ 6-29
Z
zoom.to$() ............................... 40-9
Functions reference
53-12
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Advertisement
Application locks
ASCII conversion
Audit information
Bit operations
Business Chart Manager
Character-based windows
Colors
Company operations
Application locks are used to prevent other applications and users from reading or modifying data during critical operations. This helps ensure data integrity and prevents conflicts when multiple users or programs are accessing the same data.
Use the appl.set() function to create an application lock. You need to specify a unique name for the lock and the type of lock you want to set (read, write, or exclusive).
There are three main types of application locks: read locks, write locks, and exclusive locks. You can also combine an application-wide lock with any of these types to apply the lock to all companies.
Use the appl.get.user() function to retrieve the user's login name associated with a specific application lock.
Audit files store information about data changes and updates in the system. These files are used for tracking and tracing changes made to data, ensuring accountability and compliance.
How can a 3GL window be resized?
A 3GL window can be resized using the resize.window() function. This function resizes the current window, and the new width and height must be specified in pixels. There is no need to refresh the window after using this function.
Login to continue
