SysWorks

Callable Routines Reference Manual

Order Number: SWRK-RRM-35

August 2009

This manual provides reference information about the various callable routine interfaces to SysWorks.

Revision/Update Information: This manual supercedes the SysWorks^tm Callable Routines Reference Manuual V3.4-1

Operating System: OpenVMS VAX V7.2 or higher;
OpenVMS Alpha V7.2 or higher;
DECwindows/Motif V1.2-3 or higher

Software Version: SysWorks^tm V3.5

Copyright ©1987 - 2009 Corpita Pty Ltd

Printed in Australia

The following are trademarks of Compaq Computer Corporation: ACMS, ALL-IN-1, AXP, BASIC, Bookreader, CDA, CI, DATATRIEVE, DBMS, DDIF, DEC, DEC ACCESSWORKS, DEC Ada, DEC C, DEC Fortran, DEC Pascal, DECdecision, DECdesign, DECdirect, DECdns, DECdocument, DECdtm, DECforms, DECimage, DECintact, DECmigrate, DECnet, DECnet/OSI, DECset, DECsupport, DECtp, DECwindows, Digital, DTIF, EDT, HSC, MASSBUS, MicroVAX, MicroVAX II, MSCP, OpenVMS, OpenVMS Cluster, RA, StorageWorks, TA, TMSCP, TURBOchannel, ULTRIX, VAX, VAX C, VAX MACRO, VAX-11/780, VAXcluster, VAXELN, VAXft, VAXstation, VIDA, VMS, VMScluster, VT100, and the DIGITAL logo.

PostScript is a registered trademark of Adobe Systems Inc.

Motif is a registered trademark of Open Software Foundation, Inc.

Oracle is a registered trademark, and Oracle CDD/Repository, Oracle CODASYL DBMS, Oracle Expert, Oracle Rally, Oracle Rdb, Oracle Trace and Rdb7 are trademarks of Oracle Corporation.

OSI is a registered trademark of CA Management, Inc

All other trademarks and registered trademarks are the property of their respective holders.

This document was prepared using DECdocument V3.3.

Contents Index

We welcome your comments on this manual or any SysWorks manual. If you have suggestions for improvements or find any errors, please indicate the chapter, section and page number (if available). Your input is valuable in improving future releases of our documentation.

You can send comments to us in the following ways:

Email---http://www.sysworks.com.au/contact.php
Phone---+61 (03) 9411 4411
FAX ---+61 (03) 9411 4499

Postal service

SysWorks Corpita Pty Ltd 15 Bedford Street Collingwood VIC 3066 Australia

Preface

This manual provides reference information about the various callable routine interfaces to SysWorks^tm.

Intended Audience

This manual is intended for SysWorks^tm application developers who have a working knowledge of the underlying Digital products.

Conventions

The following conventions are used in this document:

Conventions Description

[Ctrl/X] A sequence such as [Ctrl/X] indicates that you must hold down the key labeled [Ctrl] while you press another key or a pointing device button.

[] In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one or all of the choices.
In system prompts indicates the default value which will be assumed if the Return key is pressed without first entering a value.

{} In format descriptions, braces surround a required choice of options; you must choose one of the options listed.

| In format descriptions, vertical bars separate the options. If the options are enclosed in brackets (i.e. []) you can select none, one or all of the choices. If the options are enclosed in braces (i.e. {}) you must choose one of the options listed.

() In system prompts, parenthesis indicate the list of values one of which may be entered. The values are separated by a forward slash "/"

... An elipsis indicates that a value within a range may be chosen or a syntax repeated. A range may be indicated by a pair of end values, or an end value and an end keyword. For example Disk quota (0..unlimited) indicates that the keyword unlimited may be used to represent the highest possible disk quota.

italic text Italicized words and letters indicate that you should substitute a word or value of your choice.

UPPERCASE TEXT Uppercase letters indicate the name of a command or routine.

monospace text Normal monospace text indicates system prompts and output.

bold monospace text Bold monospace text indicates user responses to system prompts.

bold monospace italic text Bold monospace italic text indicates user responses to system prompts which need approriate value substitution.

mouse The term mouse is used to refer to any pointing device such as a mouse, a puck or a stylus.

MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)

Conventions	Description
`[Ctrl/X]`	A sequence such as `[Ctrl/X]` indicates that you must hold down the key labeled `[Ctrl]` while you press another key or a pointing device button.
[]	In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one or all of the choices. In system prompts indicates the default value which will be assumed if the Return key is pressed without first entering a value.
{}	In format descriptions, braces surround a required choice of options; you must choose one of the options listed.
\|	In format descriptions, vertical bars separate the options. If the options are enclosed in brackets (i.e. []) you can select none, one or all of the choices. If the options are enclosed in braces (i.e. {}) you must choose one of the options listed.
()	In system prompts, parenthesis indicate the list of values one of which may be entered. The values are separated by a forward slash "/"
...	An elipsis indicates that a value within a range may be chosen or a syntax repeated. A range may be indicated by a pair of end values, or an end value and an end keyword. For example Disk quota (0..unlimited) indicates that the keyword unlimited may be used to represent the highest possible disk quota.
italic text	Italicized words and letters indicate that you should substitute a word or value of your choice.
UPPERCASE TEXT	Uppercase letters indicate the name of a command or routine.
monospace text	Normal monospace text indicates system prompts and output.
bold monospace text	Bold monospace text indicates user responses to system prompts.
bold monospace italic text	Bold monospace italic text indicates user responses to system prompts which need approriate value substitution.
mouse	The term mouse is used to refer to any pointing device such as a mouse, a puck or a stylus.
MB1, MB2, MB3	MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)

Unless otherwise noted, all numeric values are represented in decimal notation.

Part 1
General Information

This section contains general information about SysWorks^tm programming interfaces.

Chapter 1
Callable Routines Reference

This chapter provides the reference information for the callable routine interfaces provides by SysWorks^tm.

Part 2
SWRK_ Reference Section

This section contains detailed discussions about routines provided by the SysWorks SWRKSHR runtime library.

SWRK_ADD_OBJECT

The SWRK_ADD_OBJECT routine ...

Format

status =SWRK_ADD_OBJECT(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_ADD_OBJECT routine ...

SWRK_ALLOCATE_BITS

The SWRK_ALLOCATE_BITS routine ...

Format

status =SWRK_ALLOCATE_BITS(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_ALLOCATE_BITS routine ...

SWRK_ALLOCATE_MEMORY

The SWRK_ALLOCATE_MEMORY routine ...

Format

status =SWRK_ALLOCATE_MEMORY(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_ALLOCATE_MEMORY routine ...

SWRK_APPEND_ITEM_TO_LNKLST

The SWRK_APPEND_ITEM_TO_LNKLST routine ...

Format

status =SWRK_APPEND_ITEM_TO_LNKLST(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_APPEND_ITEM_TO_LNKLST routine ...

SWRK_APPEND_LNKLST_TO_LNKLST

The SWRK_APPEND_LNKLST_TO_LNKLST routine ...

Format

status =SWRK_APPEND_LNKLST_TO_LNKLST(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_APPEND_LNKLST_TO_LNKLST routine ...

SWRK_APPEND_STRING_TO_LNKLST

The SWRK_APPEND_STRING_TO_LNKLST routine ...

Format

status =SWRK_APPEND_STRING_TO_LNKLST(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_APPEND_STRING_TO_LNKLST routine ...

SWRK_BACKUP_FILE

The SWRK_BACKUP_FILE routine ...

Format

status =SWRK_BACKUP_FILE(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_BACKUP_FILE routine ...

SWRK_BINARY_SEARCH

The SWRK_BINARY_SEARCH routine searches an ordered array of keywords.

Format

status =SWRK_BINARY_SEARCH(index, num, table, keyword )

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

index

VMS usage: index

type: integer (unsigned)

access: write only

mechanism: by reference

Specifies the address of the returned index of the matching keyword. If there was no match, this value is undefined.
num

VMS usage: length

type: integer (unsigned)

access: read only

mechanism: by value

Specifies the number of keywords (or rows) in the keyword table array.
table

VMS usage: structure

type: array

access: read only

mechanism: by reference

Specifies the table of keywords. Each element consists of three longwords. The first is the length of the keyword. The second is the address of the keyword. The third is the keyword value.
keyword

VMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Specifies the keyword which will be searched for.

Description

The SWRK_BINARY_SEARCH routine searches for the keyword in the ordered keyword table using a binary search. It allows the use of unambiguous abbreviations.

Return Values

SWRK__ABRKEYVAL Keyword was found and was an unambiguous abbreviation. The index argument received the index of the keyword within the table.

SWRK__AMBKEYVAL Keyword was found but was an ambiguous abbreviation.

SWRK__EXAKEYVAL Keyword was found as an exact match. The index argument received the index of the keyword within the table.

SWRK__UNKKEYVAL Keyword was not found.

SWRK_BITMAP_OPERATION_2

The SWRK_BITMAP_OPERATION_2 routine ...

Format

status =SWRK_BITMAP_OPERATION_2(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_BITMAP_OPERATION_2 routine ...

SWRK_BITMAP_OPERATION_3

The SWRK_BITMAP_OPERATION_3 routine ...

Format

status =SWRK_BITMAP_OPERATION_3(arg1, [arg2])

RETURNS

VMS usage: cond_value

type: integer (unsigned)

access: write only

mechanism: by value in R0

Arguments

arg1

VMS usage: arg1_type

type: integer (unsigned)

access: read only

mechanism: by reference

Specifies arg1...
arg2

VMS usage: arg2_type

type: character string

access: read only

mechanism: by descriptor

Specifies arg2...

Description

The SWRK_BITMAP_OPERATION_3 routine ...

VMS usage:	cond_value
type:	integer (unsigned)
access:	write only
mechanism:	by value in R0

VMS usage:	arg1_type
type:	integer (unsigned)
access:	read only
mechanism:	by reference

VMS usage:	arg2_type
type:	character string
access:	read only
mechanism:	by descriptor

VMS usage:	index
type:	integer (unsigned)
access:	write only
mechanism:	by reference

VMS usage:	length
type:	integer (unsigned)
access:	read only
mechanism:	by value

VMS usage:	structure
type:	array
access:	read only
mechanism:	by reference

VMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

SWRK__ABRKEYVAL	Keyword was found and was an unambiguous abbreviation. The index argument received the index of the keyword within the table.
SWRK__AMBKEYVAL	Keyword was found but was an ambiguous abbreviation.
SWRK__EXAKEYVAL	Keyword was found as an exact match. The index argument received the index of the keyword within the table.
SWRK__UNKKEYVAL	Keyword was not found.

SysWorks

Callable Routines Reference Manual

August 2009

Copyright ©1987 - 2009 Corpita Pty Ltd

Preface

Intended Audience

Conventions

Part 1General Information

Chapter 1Callable Routines Reference

Part 2SWRK_ Reference Section

SWRK_ADD_OBJECT

Format

status =SWRK_ADD_OBJECT(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_ALLOCATE_BITS

Format

status =SWRK_ALLOCATE_BITS(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_ALLOCATE_MEMORY

Format

status =SWRK_ALLOCATE_MEMORY(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_APPEND_ITEM_TO_LNKLST

Format

status =SWRK_APPEND_ITEM_TO_LNKLST(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_APPEND_LNKLST_TO_LNKLST

Format

status =SWRK_APPEND_LNKLST_TO_LNKLST(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_APPEND_STRING_TO_LNKLST

Format

status =SWRK_APPEND_STRING_TO_LNKLST(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_BACKUP_FILE

Format

status =SWRK_BACKUP_FILE(arg1, [arg2])

RETURNS

Arguments

arg1

arg2

Description

See also

SWRK_BINARY_SEARCH

Format

status =SWRK_BINARY_SEARCH(index, num, table, keyword )

RETURNS

Arguments

index

num

Part 1
General Information

Chapter 1
Callable Routines Reference

Part 2
SWRK_ Reference Section