OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

$SYNCH

Checks the completion status of a system service that completes asynchronously.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$SYNCH [efn] ,[iosb]

C Prototype

int sys$synch (unsigned int efn, struct _iosb *iosb);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag specified in the call to the system service whose completion status is to be checked by $SYNCH. The efn argument is a longword containing this number; however, $SYNCH uses only the low-order byte.
iosb

OpenVMS usage: io_status_block

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

I/O status block specified in the call to the system service whose completion status is to be checked by $SYNCH. The iosb argument is the address of this quadword I/O status block.

Description

The Synchronize service checks the completion status of a system service that completes asynchronously. The service whose completion status is to be checked must have been called with the efn and iosb arguments specified, because the $SYNCH service uses the event flag and I/O status block of the service to be checked.
This service performs a true test for the completion of an asynchronous service, such as $GETJPI. $SYNCH operates in the following way:

When called, $SYNCH waits (by calling $WAITFR) for the event flag to be set.
When the event flag is set, $SYNCH checks to see whether the I/O status block is nonzero. If it is nonzero, then the asynchronous service has completed, and $SYNCH returns to the caller.
If the I/O status block is the value 0, then the asynchronous service has not yet completed and the event flag was set by the completion of an event not associated with the completion of $GETJPI. In this case, $SYNCH clears the event flag (by calling $CLREF) and waits again (by calling $WAITFR) for the event flag to be set, repeating this cycle until the I/O status block is nonzero.

The $SYNCH service always sets the specified event flag when it returns to the caller. This ensures that different program segments can use the same event flag without conflicting. For example, assume that calls to $GETJPI and $GETSYI both specify the same event flag and that $SYNCH is called to check for the completion of $GETJPI. If $GETSYI sets the event flag, $SYNCH clears the flag and waits for $GETJPI to set it. When $GETJPI sets the flag, $SYNCH returns to the caller and sets the event flag. In this way, the flag set by $GETSYI is not lost, and another call to $SYNCH will show the completion of $GETSYI.
The $SYNCH service is useful when a program calls an asynchronous service but must perform some other work before testing for the completion of the asynchronous service. In this case, the program should call $SYNCH at that point when it must know that the service has completed and when it is willing to wait for the service to actually complete.
When a program calls an asynchronous service (for example, $QIO) and actually waits in line (by calling $WAITFR) for its completion without performing any other work, you could improve that program by calling the synchronous form of that service (for example, $QIOW). The synchronous services such as $QIOW execute code that checks for the true completion status in the same way that $SYNCH does.
Required Access or Privileges

None
Required Quota

None

Condition Values Returned

SS$_NORMAL The service completed successfully. The asynchronous service has completed, and the I/O status block contains the condition value describing the completion status of the asynchronous service.

SS$_ACCVIO The I/O status block cannot be read by the caller.

SS$_ILLEFC An illegal event flag was specified.

SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

$TIMCON

Converts 128-bit Coordinated Universal Time (UTC) format to 64-bit system format or 64-bit system format to 128-bit UTC format based on the value of the convert flag.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$TIMCON [smnadr] ,[utcadr] ,cvtflg

C Protptype

int sys$timcon (struct _generic_64 *smnadr, unsigned int *utcadr [4], char cvtflg);

Arguments

smnadr

OpenVMS usage: date_time

type: quadword (unsigned)

access: read/write

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

The 64-bit system format value that $TIMCON will use in the conversion. The smnadr argument will be read from or written to based on the value of the cvtflg argument. The smnadr is required when converting UTC time to 64-bit system format.
utcadr

OpenVMS usage: coordinated universal time

type: utc_date_time

access: read/write

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

UTC time value that $TIMCON will use in the conversion. The utcadr argument will be read from or written to based on the value of the cvtflg argument. The utcadr argument is required when converting 64-bit system format to UTC time.
cvtflg

OpenVMS usage: conversion flag

type: longword (unsigned)

access: read only

mechanism: by value

A longword indicating the direction of the conversion. If the cvtflg value is 0, UTC time is converted to 64-bit system value. If the cvtflg value is 1, 64-bit system format is converted to UTC time.

Description

The Time Converter service converts 64-bit system format time to UTC format, and vice versa.
When converting a 64-bit system format time to 128-bit UTC format time, the time zone of the local system is used.
When converting a 128-bit UTC format time to a 64-bit system time, the time zone differential factor encoded in the 128-bit buffer is used.

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_INVTIME The input time cannot be converted because its value is out of the legal range or is a delta time, or the UTC is of an illegal format.

$TRNLNM

Returns information about a logical name.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$TRNLNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]

C Prototype

int sys$trnlnm (unsigned int *attr, void *tabnam, void *lognam, unsigned char *acmode, void *itmlst);

Arguments

attr

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Attributes controlling the search for the logical name. The attr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a longword bit mask specifying these attributes.
Each bit in the longword corresponds to an attribute and has a symbolic name. The $LNMDEF macro defines these symbolic names. To specify an attribute, use its symbolic name or set its corresponding bit. All undefined bits in the longword have the value 0.
If you do not specify this argument or specify it as the value 0 (no bits set), the following attribute is not used.

Attribute Description

LNM$M_CASE_BLIND If set, $TRNLNM does not distinguish between uppercase and lowercase letters in the logical name to be translated.

LNM$M_INTERLOCKED If set, $TRNLNM does not translate the current logical name until any clusterwide logical name modifications in progress are completed. This attribute is not set by default. If your application requires translation using the most recent definition of a clusterwide logical name, use this attribute to ensure that the translation is stalled until all pending modifications have been made.

tabnam

OpenVMS usage: logical_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of the logical name table or the name of a searchlist logical name that translates the name of one or more tables in which to search for the specified logical name. The tabnam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a descriptor pointing to this name. This argument is required.
The name must be entered in uppercase letters. (This requirement differs from the $CRELNT system service, which automatically changes tabnam to uppercase.)
If the table name is not the name of a logical name table, it is assumed to be a logical name and is translated iteratively until either the name of a logical name table is found or the number of translations allowed by the system have been performed. If the table name translates to a list of logical name tables, the tables are searched in the specified order.
lognam

OpenVMS usage: logical_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Logical name about which information is to be returned. The lognam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a descriptor pointing to the logical name string. This argument is required.
acmode

OpenVMS usage: access_mode

type: byte (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Access mode to be used in the translation. The acmode argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a byte specifying the access mode. The $PSLDEF macro defines symbolic names for the four access modes.
When you specify the acmode argument, $TRNLNM ignores all names (both logical names and table names) at access modes less privileged than the specified access mode. The specified access mode is not checked against that of the caller.
If you do not specify acmode, $TRNLNM performs the translation without regard to access mode; however, the translation process proceeds from the outermost to the innermost access modes. Thus, if two logical names with the same name but at different access modes exist in the same table, $TRNLNM translates the name with the outermost access mode.
itmlst

OpenVMS usage: 32-bit item_list_3 or 64-bit item_list_64b

type: longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Item list describing the information that $TRNLNM is to return. The itmlst argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a list of item descriptors, each of which specifies or controls an item of information to be returned. An item list in 32-bit format is terminated by a longword of 0; an item list in 64-bit format is terminated by a quadword of 0. All items in an item list must be of the same format---either 32-bit or 64-bit.
The following diagram depicts the 32-bit format of a single item descriptor.

Attribute	Description
LNM$M_CASE_BLIND	If set, $TRNLNM does not distinguish between uppercase and lowercase letters in the logical name to be translated.
LNM$M_INTERLOCKED	If set, $TRNLNM does not translate the current logical name until any clusterwide logical name modifications in progress are completed. This attribute is not set by default. If your application requires translation using the most recent definition of a clusterwide logical name, use this attribute to ensure that the translation is stalled until all pending modifications have been made.

The following table defines the item descriptor fields for 32-bit item list entries.

Descriptor Field Definition

Buffer length A word specifying the number of bytes in the buffer pointed to by the buffer address field.

Item code A word containing a symbolic code describing the nature of the information currently in the buffer, to be returned in the buffer, or to be returned by the buffer pointed to by the buffer address field.

Buffer address A longword containing the 32-bit address of the buffer that specifies or receives the information.

Return length address A longword containing the 32-bit address of a word specifying the actual length (in bytes) of the information returned by $TRNLNM in the buffer pointed to by the buffer address field.

Descriptor Field	Definition
Buffer length	A word specifying the number of bytes in the buffer pointed to by the buffer address field.
Item code	A word containing a symbolic code describing the nature of the information currently in the buffer, to be returned in the buffer, or to be returned by the buffer pointed to by the buffer address field.
Buffer address	A longword containing the 32-bit address of the buffer that specifies or receives the information.
Return length address	A longword containing the 32-bit address of a word specifying the actual length (in bytes) of the information returned by $TRNLNM in the buffer pointed to by the buffer address field.

The following diagram depicts the 64-bit format of a single item descriptor.

The following table defines the item descriptor fields for 64-bit item list entries.

Descriptor Field Definition

MBO The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.

Item code A word containing a symbolic code describing the nature of the information currently in the buffer, to be returned in the buffer, or to be returned by the buffer pointed to by the buffer address field.

MBMO The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.

Buffer address A quadword containing the 64-bit address of the buffer that specifies or receives the information.

Return length address A quadword containing the 64-bit address of a word specifying the actual length (in bytes) of the information returned by $TRNLNM in the buffer pointed to by the buffer address field.

Descriptor Field	Definition
MBO	The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.
Item code	A word containing a symbolic code describing the nature of the information currently in the buffer, to be returned in the buffer, or to be returned by the buffer pointed to by the buffer address field.
MBMO	The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.
Buffer address	A quadword containing the 64-bit address of the buffer that specifies or receives the information.
Return length address	A quadword containing the 64-bit address of a word specifying the actual length (in bytes) of the information returned by $TRNLNM in the buffer pointed to by the buffer address field.

Item Codes

LNM$_ACMODE
When you specify LNM$_ACMODE, $TRNLNM returns the access mode that was associated with the logical name at the time of its creation. The buffer address field in the item descriptor is the address of a byte in which $TRNLNM writes the access mode.
LNM$_ATTRIBUTES
When you specify LNM$_ATTRIBUTES, $TRNLNM returns the attributes of the logical name and the equivalence name associated with the current LNM$_INDEX value.
The buffer address field of the item descriptor points to a longword bit mask wherein each bit corresponds to an attribute. The $TRNLNM service sets the corresponding bit for each attribute possessed by either the logical name or the equivalence name.
The $LNMDEF macro defines the following symbolic names for these attributes.

Attribute Description

LNM$M_CONCEALED If $TRNLNM sets this bit, the equivalence name at the current index value for the logical name is a concealed logical name, as interpreted by OpenVMS RMS.

LNM$M_CONFINE If $TRNLNM sets this bit, the logical name is not copied from a process to any of its spawned subprocesses. The DCL command SPAWN creates subprocesses.

LNM$M_CRELOG If $TRNLNM sets this bit, the logical name was created using the $CRELOG system service.

LNM$M_EXISTS If $TRNLNM sets this bit, an equivalence name with the specified index does exist.

LNM$M_NO_ALIAS If $TRNLNM sets this bit, the name of the logical name cannot be given to another logical name defined in the same table at an outer access mode.

LNM$M_TABLE If $TRNLNM sets this bit, the logical name is the name of a logical name table.

LNM$M_CLUSTERWIDE If $TRNLNM sets this bit, the logical name is in a clusterwide table.

LNM$M_TERMINAL If $TRNLNM sets this bit, the equivalence name for the logical name cannot be subjected to further (recursive) logical name translation.

LNM$_CHAIN
When you specify LNM$_CHAIN, $TRNLNM processes another item list immediately following the current item list. The LNM$_CHAIN item code must be the last one in the current item list. The buffer address field of the item descriptor points to the next item list.
You can chain together 32-bit and 64-bit item lists.
LNM$_INDEX
When you specify LNM$_INDEX, $TRNLNM searches for an equivalence name that has the specified index value. The buffer address field of the item descriptor points to a longword containing a user-specified integer in the range 0 to 127.
If you do not specify this item code, the implied value of LNM$_INDEX is 0 and $TRNLNM returns information about the equivalence name at index 0.
Because a logical name can have more than one equivalence name and each equivalence name is identified by an index value, you should specify the LNM$_INDEX item code first in the item list, before specifying LNM$_STRING, LNM$_LENGTH, or LNM$_ATTRIBUTES. These item codes return information about the equivalence name identified by the current index value, LNM$_INDEX.
LNM$_LENGTH
When you specify LNM$_LENGTH, $TRNLNM returns the length of the equivalence name string corresponding to the current LNM$_INDEX value. The buffer address field in the item descriptor is the address of the longword in which $TRNLNM writes this length.
If an equivalence name does not exist at the current LNM$_INDEX value, $TRNLNM returns the value 0 to the longword pointed to by the return length field of the item descriptor.
LNM$_MAX_INDEX
Each equivalence name for the logical name has an index associated with it. When you specify LNM$_MAX_INDEX, $TRNLNM returns a value equal to the largest equivalence name index. The buffer address field in the item descriptor is the address of a longword in which $TRNLNM writes this value. If the logical name exists but has no equivalence name (and, therefore, no index value), $TRNLNM returns a value of --1.
LNM$_STRING
When you specify LNM$_STRING, $TRNLNM returns the equivalence name string corresponding to the current LNM$_INDEX value. The buffer address field of the item descriptor points to a buffer containing this string. The return length address field of the item descriptor contains an address of a word that contains the length of this string in bytes. The maximum length of the equivalence name string is 255 characters.
If an equivalence name does not exist at the current LNM$_INDEX value, $TRNLNM returns the value 0 in the return length address field of the item descriptor.
LNM$_TABLE
When you specify LNM$_TABLE, $TRNLNM returns the name of the table containing the logical name being translated. The buffer address field of the item descriptor points to the buffer in which $TRNLNM returns this name. The return length address field of the item descriptor specifies the address of a word in which $TRNLNM writes the size of the table name. The maximum length of the table name is 31 characters.

Attribute	Description
LNM$M_CONCEALED	If $TRNLNM sets this bit, the equivalence name at the current index value for the logical name is a concealed logical name, as interpreted by OpenVMS RMS.
LNM$M_CONFINE	If $TRNLNM sets this bit, the logical name is not copied from a process to any of its spawned subprocesses. The DCL command SPAWN creates subprocesses.
LNM$M_CRELOG	If $TRNLNM sets this bit, the logical name was created using the $CRELOG system service.
LNM$M_EXISTS	If $TRNLNM sets this bit, an equivalence name with the specified index does exist.
LNM$M_NO_ALIAS	If $TRNLNM sets this bit, the name of the logical name cannot be given to another logical name defined in the same table at an outer access mode.
LNM$M_TABLE	If $TRNLNM sets this bit, the logical name is the name of a logical name table.
LNM$M_CLUSTERWIDE	If $TRNLNM sets this bit, the logical name is in a clusterwide table.
LNM$M_TERMINAL	If $TRNLNM sets this bit, the equivalence name for the logical name cannot be subjected to further (recursive) logical name translation.

Description

The Translate Logical Name service returns information about a logical name. You need read access to a shareable logical name table to translate a logical name located in that shareable logical name table.
For conventions regarding logical names for process-permanent files, refer to the chapter "Logical Name Services" in the OpenVMS Programming Concepts Manual.
Required Access or Privileges

Read access is required.
Required Quota

None
Related Services

$ADJSTK, $ADJWSL, $CRELNM, $CRELNT, $CRETVA, $CRMPSC, $DELLNM, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULWSET, $UPDSEC, $UPDSECW

Condition Values Returned

SS$_NORMAL The service completed successfully. An equivalence name for the logical name has been found.

SS$_ACCVIO The service cannot access the location or locations specified by one or more arguments.

SS$_BADPARAM One or more arguments have an invalid value, or a logical name table name or logical name was not specified. Or, an item list containing both 32-bit and 64-bit item list entries was found.

SS$_BUFFEROVF The service completed successfully. The buffer length field in an item descriptor specified an insufficient value, so the buffer was not large enough to hold the requested data.

SS$_IVLOGNAM The tabnam argument or lognam argument specifies a string whose length is not in the required range of 1 through 255 characters.

SS$_IVLOGTAB The tabnam argument does not specify a logical name table.

SS$_NOLOGNAM The logical name was not found in the specified logical name table or tables.

SS$_NOPRIV The caller lacks the necessary privilege to access the specified name.

SS$_TOOMANYLNAM Logical name translation of the table name exceeded the allowable depth (10 translations).

Contents

Index

privacy and legal statement

4527PRO_094.HTML

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

SS$_NORMAL	The service completed successfully. The asynchronous service has completed, and the I/O status block contains the condition value describing the completion status of the asynchronous service.
SS$_ACCVIO	The I/O status block cannot be read by the caller.
SS$_ILLEFC	An illegal event flag was specified.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

OpenVMS usage:	date_time
type:	quadword (unsigned)
access:	read/write
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	coordinated universal time
type:	utc_date_time
access:	read/write
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	conversion flag
type:	longword (unsigned)
access:	read only
mechanism:	by value

SS$_NORMAL	The service completed successfully.
SS$_INVTIME	The input time cannot be converted because its value is out of the legal range or is a delta time, or the UTC is of an illegal format.

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	logical_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism:	by 32-bit descriptor--fixed-length string descriptor (VAX)

OpenVMS usage:	access_mode
type:	byte (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	32-bit item_list_3 or 64-bit item_list_64b
type:	longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

SS$_NORMAL	The service completed successfully. An equivalence name for the logical name has been found.
SS$_ACCVIO	The service cannot access the location or locations specified by one or more arguments.
SS$_BADPARAM	One or more arguments have an invalid value, or a logical name table name or logical name was not specified. Or, an item list containing both 32-bit and 64-bit item list entries was found.
SS$_BUFFEROVF	The service completed successfully. The buffer length field in an item descriptor specified an insufficient value, so the buffer was not large enough to hold the requested data.
SS$_IVLOGNAM	The tabnam argument or lognam argument specifies a string whose length is not in the required range of 1 through 255 characters.
SS$_IVLOGTAB	The tabnam argument does not specify a logical name table.
SS$_NOLOGNAM	The logical name was not found in the specified logical name table or tables.
SS$_NOPRIV	The caller lacks the necessary privilege to access the specified name.
SS$_TOOMANYLNAM	Logical name translation of the table name exceeded the allowable depth (10 translations).