OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

The access mode of the calling process must be equal to or more privileged than the access mode at which the lock was initially granted.

When locking on a resource is clusterwide, a single master copy of the resource is maintained on the node that owns the process that created the resource by taking out the first lock on it. When a process on another node locks that same resource, a local copy of the resource is copied to the node and the lock is identified by a lock ID that is unique to that node.

In a cluster environment, however, you cannot use $GETLKI to obtain directly information about locks on other nodes in the cluster; that is, you cannot specify in a call to $GETLKI the lock ID of a lock held by a process on another node. The $GETLKI service interprets the lkidadr argument as the lock ID of a lock on the caller's node, even though the resource associated with a lock might have its master copy on the caller's node.

However, because a process on another node in the cluster can have a lock on the same resource as the caller of $GETLKI, the caller, in obtaining information about the resource, can indirectly obtain some information about locks on the resource that are held by processes on other nodes. One example of information indirectly obtained about a resource is the contents of lock queues; these queues contain information about all locks on the resource, and some of these locks can be held by processes on other nodes.

Another example of information more directly obtained is the remote lock ID of a lock held by a process on another node. Specifically, if the caller of $GETLKI on node A specifies a lock (by means of lkidadr) and that lock is held by a process on node B, $GETLKI returns the lock ID of the lock from node B's lock database if the LKI$_REMLKID item code is specified in the call.

Item codes LKI$_BLOCKEDBY, LKI$_BLOCKING, LKI$_LOCKS, and LKI$_STATE specify that $GETLKI return various items of information; some of these items are the names of lock modes or the names of lock queues. The $LCKDEF macro defines the following symbolic names.

Symbolic Name Lock Mode

LCK$K_NLMODE Null mode

LCK$K_CRMODE Concurrent read mode

LCK$K_CWMODE Concurrent write mode

LCK$K_PRMODE Protected read mode

LCK$K_PWMODE Protected write mode

LCK$K_EXMODE Exclusive mode

Symbolic Name Queue Name

LKI$C_GRANTED Granted queue, holding locks that have been granted

LKI$C_CONVERT Converting queue, holding locks that are currently being converted to another lock mode

LKI$C_WAITING Waiting queue, holding locks that are neither granted nor converting (for example, a blocked lock)

Symbolic Name	Lock Mode
LCK$K_NLMODE	Null mode
LCK$K_CRMODE	Concurrent read mode
LCK$K_CWMODE	Concurrent write mode
LCK$K_PRMODE	Protected read mode
LCK$K_PWMODE	Protected write mode
LCK$K_EXMODE	Exclusive mode

Symbolic Name	Queue Name
LKI$C_GRANTED	Granted queue, holding locks that have been granted
LKI$C_CONVERT	Converting queue, holding locks that are currently being converted to another lock mode
LKI$C_WAITING	Waiting queue, holding locks that are neither granted nor converting (for example, a blocked lock)

Required Access or Privileges

Depending on the operation, the calling process might need one of the following privileges to use $GETLKI:

For locks held by other processes, you need to have joined the resource domain for lock access or hold WORLD privileges.
You need WORLD privilege to obtain information about locks held by processes in other groups.
To obtain information about system locks, either you need SYSLCK privilege or the process must be executing in executive or kernel access mode.

To establish a default resource domain, it is necessary to have performed either a call to $SET_RESOURCE_DOMAIN or a previous call to $ENQ[W].

Required Quota

The caller must have sufficient ASTLM or BYTLM quota.

Related Services

$DEQ, $ENQ, $ENQW, $GETLKIW, $SET_RESOURCE_DOMAIN

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The item list cannot be read; the areas specified by the buffer address and return length address fields in the item descriptor cannot be written; or the location specified by the lkidadr argument cannot be written.

SS$_BADPARAM You specified an invalid item code.

SS$_EXQUOTA The caller has insufficient ASTLM or BYTLM quota.

SS$_ILLRSDM The operation attempted is not allowed on the resource. Use SHOW SECURITY to verify the access allowed to the specified resource domain.

SS$_INSFMEM The nonpaged dynamic memory is insufficient for the operation.

SS$_IVLOCKID The lkidadr argument specified an invalid lock ID.

SS$_IVMODE A more privileged access mode is required.

SS$_NOMORELOCK The caller requested a wildcard operation by specifying a value of 0 or --1 for the lkidadr argument, and $GETLKI has exhausted the locks about which it can return information to the caller; or no lkidadr argument is specified. This is an alternate success status.

SS$_NOSYSLCK The caller attempted to acquire information about a systemwide lock and did not have the required SYSLCK privilege.

SS$_NOWORLD The caller attempted to acquire information about a lock held by a process in another group and did not have the required WORLD privilege.

Condition Values Returned in the I/O Status Block

Same as those returned in R0.

$GETLKIW

Returns information about the lock database on a system.
The $GETLKIW service completes synchronously; that is, it returns to the caller with the requested information.
For asynchronous completion, use the Get Lock Information ($GETLKI) service; $GETLKI returns to the caller after queuing the information request, without waiting for the information to be returned.
In all other respects, $GETLKIW is identical to $GETLKI. For all other information about the $GETLKIW service, refer to the description of $GETLKI in this manual.
The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together provide the user interface to the Lock Management facility. Refer to the descriptions of these other services for additional information about lock management.

Format

SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$getlkiw (unsigned int efn, unsigned int *lkidadr, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int reserved);

$GETMSG

Returns message text associated with a given message identification code into the caller's buffer. The message can be from the system message file or a user-defined message.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$GETMSG msgid ,msglen ,bufadr ,[flags] ,[outadr]

C Prototype

int sys$getmsg (unsigned int msgid, unsigned short int *msglen, void *bufadr, unsigned int flags, unsigned char outadr [4]);

Arguments

msgid

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by value

Identification of the message to be retrieved. The msgid argument is a longword value containing the message identification. Each message has a unique identification, contained in bits 3 through 27 of system longword condition values.
msglen

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

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

mechanism: by 32-bit reference (VAX)

Length of the message string returned by $GETMSG. The msglen argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a word into which $GETMSG writes this length.
bufadr

OpenVMS usage: char_string

type: character-coded text string

access: write only

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

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

Buffer to receive the message string. The bufadr argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a character string descriptor pointing to the buffer into which $GETMSG writes the message string. The maximum size of any message string is 256 bytes.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Message components to be returned. The flags argument is a longword bit vector wherein a bit, when set, specifies that the message component is to be returned. The following table describes the significant bits.

Bit Value Description

0 1 Include text of message

0 Do not include text of message

1 1 Include message identifier

0 Do not include message identifier

2 1 Include severity indicator

0 Do not include severity indicator

3 1 Include facility name

0 Do not include facility name

If you omit this argument in a VAX MACRO or BLISS-32 service call, it defaults to a value of 15; that is, all flags are set and all components of the message are returned. If you omit this argument in a Fortran service call, it defaults to a value of 0; the value 0 causes $GETMSG to use the process default flags.
outadr

OpenVMS usage: vector_byte_unsigned

type: byte (unsigned)

access: write only

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

mechanism: by 32-bit reference (VAX)

Optional information to be returned by $GETMSG. The outadr argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a 4-byte array into which $GETMSG writes the following information.

Byte Contents

0 Reserved

1 Count of FAO arguments associated with message

2 User-specified value in message, if any

3 Reserved

Bit	Value	Description
0	1	Include text of message
	0	Do not include text of message
1	1	Include message identifier
	0	Do not include message identifier
2	1	Include severity indicator
	0	Do not include severity indicator
3	1	Include facility name
	0	Do not include facility name

Byte	Contents
0	Reserved
1	Count of FAO arguments associated with message
2	User-specified value in message, if any
3	Reserved

Description

The Get Message service locates and returns message text associated with a given message identification code into the caller's buffer. The message can be from the system message file or a user-defined message. The operating system uses this service to retrieve messages based on unique message identifications and to prepare to output the messages.
The message identifications correspond to the symbolic names for condition values returned by system components; for example, SS$_code from system services, RMS$_code for RMS messages, and so on.
When you set all bits in the flags argument, $GETMSG returns a string in the following format:
facility-severity-ident, message-text
where:

facility Identifies the component of the operating system

severity Is the severity code (the low-order three bits of the condition value)

ident Is the unique message identifier

message-text Is the text of the message

For example, if you specify the MSGID=#SS$_DUPLNAM argument, the $GETMSG service returns the following string:
%SYSTEM-F-DUPLNAM, duplicate process name
You can define your own messages with the Message utility. See the OpenVMS System Management Utilities Reference Manual for additional information.
The message text associated with a particular 32-bit message identification can be retrieved from one of several places. This service takes the following steps to locate the message text:
All message sections linked into the currently executing image are searched for the associated information.
If the information is not found, the process-permanent message file is searched. (You can specify the process-permanent message file by using the SET MESSAGE command.)
If the information is not found, the systemwide message file is searched.
If the information is not found, the SS$_MSGNOTFND condition value is returned in R0 and a message in the following form is returned to the caller's buffer:
%facility-severity-NONAME, message=xxxxxxxx[hex], (facility=n, message=n[dec])
Required Access or Privileges

None
Required Quota

None
Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BUFFEROVF The service completed successfully. The string returned overflowed the buffer provided and has been truncated.

SS$_INSFARG The call arguments are insufficient.

SS$_MSGNOTFND The service completed successfully; however, the message code cannot be found, and a default message has been returned.

Example


#include <stdio.h> #include <ssdef.h> #include <stsdef.h> #include <descrip.h> #include <starlet.h> int status, /* Status of system calls / msg_flag = 0x0001, / Text only / msg_code = SS$_DUPLNAM; / Message code to retrieve / short int outlen; / Length of output string from $FAO / char out_buffer[256], / Buffer for $FAO output / msg_info[4]; / Buffer for message information / $DESCRIPTOR(out_desc, out_buffer); / VMS Descriptor for out_buffer / main() { status = sys$getmsg(msg_code, / Error message number / &outlen, / Length of retrived message / &out_desc, / Descriptor for output buffer / msg_flag, / Message options flag / msg_info); / Return information area / if ((status & STS$M_SUCCESS) != 0) { / $GETMSG directive succeeded, output resultant string / out_buffer[outlen] = '\0'; / add string terminator to buffer / puts(out_buffer); / output the result */ } return (status); }

#include <stdio.h> 
#include <ssdef.h> 
#include <stsdef.h> 
#include <descrip.h> 
#include <starlet.h> 
 
int     status,                         /* Status of system calls */ 
        msg_flag = 0x0001,              /* Text only */ 
        msg_code = SS$_DUPLNAM;         /* Message code to retrieve */ 
short int 
        outlen;                         /* Length of output string from $FAO */ 
 
char    out_buffer[256],                /* Buffer for $FAO output */ 
        msg_info[4];                    /* Buffer for message information */ 
 
$DESCRIPTOR(out_desc, out_buffer);      /* VMS Descriptor for out_buffer */ 
 
main() 
{ 
    status = sys$getmsg(msg_code,       /* Error message number */ 
                        &outlen,        /* Length of retrived message */ 
                        &out_desc,      /* Descriptor for output buffer */ 
                        msg_flag,       /* Message options flag */ 
                        msg_info);      /* Return information area */ 
 
    if ((status & STS$M_SUCCESS) != 0) 
    { 
        /* $GETMSG directive succeeded, output resultant string */ 
        out_buffer[outlen] = '\0';      /* add string terminator to buffer */ 
        puts(out_buffer);               /* output the result */ 
    } 
    return (status); 
}

This example shows a segment of a program used to obtain only the text portion of the message associated with the system message code SS$_DUPLNAM. The $GETMSG service returns the following string:
duplicate process name

$GETQUI

Returns information about queues and the jobs initiated from those queues.
The $GETQUI service completes asynchronously; for synchronous completion, use the Get Queue Information and Wait ($GETQUIW) service.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.

Format

SYS$GETQUI [efn] ,func [,context] [,itmlst] [,iosb] [,astadr] [,astprm]

C Prototype

int sys$getqui (unsigned int efn, unsigned short int func, unsigned int *context, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag to be set when $GETQUI completes. The efn argument is a longword containing this number; however, $GETQUI uses only the low-order byte. The efn argument is optional.
When the request is queued, $GETQUI clears the specified event flag (or event flag 0 if efn was not specified). Then, when the operation completes, $GETQUI sets the specified event flag (or event flag 0).
func

OpenVMS usage: function_code

type: word (unsigned)

access: read only

mechanism: by value

Function code specifying the function that $GETQUI is to perform. The func argument is a word containing this function code. The $QUIDEF macro defines the names of each function code.
You can specify only one function code in a single call to $GETQUI. Most function codes require or allow for additional information to be passed in the call. You pass this information by using the itmlst argument, which specifies a list of one or more item descriptors. Each item descriptor in turn specifies an item code, which either describes the specific information to be returned by $GETQUI, or otherwise affects the action designated by the function code.
You can use wildcard mode to make a sequence of calls to $GETQUI to get information about all characteristics, form definitions, queues, or jobs contained in the system job queue file. For information on using wildcard mode, see the Description section.
context

OpenVMS usage: context

type: longword (unsigned)

access: modify

mechanism: by reference

Address of a longword containing the number of a context stream for this call to the $GETQUI system service. If the argument is unspecified or 0, the service uses the default context stream (#0).
To generate a new context stream, the specified longword must contain --1. $GETQUI then modifies the longword to hold the context number for that stream of operation. The context is marked with the caller's mode (user, supervisor, executive, or kernel). Any attempt to use that context in successive calls is checked and no call from a mode outside the recorded mode is allowed access.
To clean up a context, make a $GETQUI call using the QUI$_CANCEL_OPERATION function code and specify the address of the context number as the context argument.
itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list supplying information to be used in performing the function specified by the func argument. The itmlst argument is the address of the item list. The item list consists of one or more item descriptors, each of which contains an item code. The item list is terminated by an item code of 0 or by a longword of 0. The following diagram depicts the structure of a single item descriptor.

The following table defines the item descriptor fields.

Descriptor Field Definition

Buffer length A word specifying the length of the buffer; the buffer either supplies information to $GETQUI or receives information from $GETQUI. The required length of the buffer varies, depending on the item code specified, and is given in the description of each item code.

Item code A word containing an item code, which identifies the nature of the information supplied for $GETQUI or which is received from $GETQUI. Each item code has a symbolic name; the $QUIDEF macro defines these symbolic names.

Buffer address Address of the buffer that specifies or receives the information.

Return length address Address of a word to receive the length of information returned by $GETQUI.

Descriptor Field	Definition
Buffer length	A word specifying the length of the buffer; the buffer either supplies information to $GETQUI or receives information from $GETQUI. The required length of the buffer varies, depending on the item code specified, and is given in the description of each item code.
Item code	A word containing an item code, which identifies the nature of the information supplied for $GETQUI or which is received from $GETQUI. Each item code has a symbolic name; the $QUIDEF macro defines these symbolic names.
Buffer address	Address of the buffer that specifies or receives the information.
Return length address	Address of a word to receive the length of information returned by $GETQUI.

The item codes' symbolic names have the following format:

QUI$_code

There are two types of item code:

Input value item code. The $GETQUI service has only five input value item codes: QUI$_SEARCH_FLAGS, QUI$_SEARCH_JOB_NAME, QUI$_SEARCH_NAME, QUI$_SEARCH_NUMBER, and QUI$_SEARCH_USERNAME. These item codes specify the object name or number for which $GETQUI is to return information and the extent of $GETQUI's search for these objects. Most function codes require that you specify at least one input value item code. The function code or codes for which each item code is valid are shown in parentheses after the item code description.
For input value item codes, the buffer length and buffer address fields of the item descriptor must be nonzero; the return length field must be zero. Specific buffer length requirements are given in the description of each item code.
Output value item code. Output value item codes specify a buffer for information returned by $GETQUI. For output value item codes, the buffer length and buffer address fields of the item descriptor must be nonzero; the return length field can be zero or nonzero. Specific buffer length requirements are given in the description of each item code.

Several item codes specify a queue name, form name, or characteristic name to $GETQUI or request that $GETQUI return one of these names. For these item codes, the buffer must specify or be prepared to receive a string containing from 1 to 31 characters, exclusive of spaces, tabs, and null characters, which are ignored. Allowable characters in the string are uppercase alphabetic characters, lowercase alphabetic characters (which are converted to uppercase), numeric characters, the dollar sign ($), and the underscore (_).

See the Item Codes section for a description of the $GETQUI item codes.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

I/O status block into which $GETQUI writes the completion status after the requested operation has completed. The iosb argument is the address of the I/O status block.

At request initiation, $GETQUI sets the value of the quadword I/O status block to 0. When the requested operation has completed, $GETQUI writes a condition value in the first longword of the I/O status block. It writes the value 0 into the second longword; this longword is unused and reserved for future use.

Contents

Index

Legal

 
4527PRO_046.HTML

OpenVMS System Services Reference Manual

Condition Values Returned

Condition Values Returned in the I/O Status Block

$GETLKIW

Format

SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$getlkiw (unsigned int efn, unsigned int lkidadr, void itmlst, struct _iosb iosb, void (astadr)(__unknown_params), int astprm, unsigned int reserved);

$GETMSG

Format

SYS$GETMSG msgid ,msglen ,bufadr ,[flags] ,[outadr]

C Prototype

int sys$getmsg (unsigned int msgid, unsigned short int msglen, void bufadr, unsigned int flags, unsigned char outadr [4]);

Arguments

msgid

msglen

bufadr

flags

outadr

Description

Condition Values Returned

Example

$GETQUI

Format

SYS$GETQUI [efn] ,func [,context] [,itmlst] [,iosb] [,astadr] [,astprm]

C Prototype

int sys$getqui (unsigned int efn, unsigned short int func, unsigned int context, void itmlst, struct _iosb iosb, void (astadr)(__unknown_params), int astprm);

Arguments

efn

func

context

itmlst

iosb

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read; the areas specified by the buffer address and return length address fields in the item descriptor cannot be written; or the location specified by the lkidadr argument cannot be written.
SS$_BADPARAM	You specified an invalid item code.
SS$_EXQUOTA	The caller has insufficient ASTLM or BYTLM quota.
SS$_ILLRSDM	The operation attempted is not allowed on the resource. Use SHOW SECURITY to verify the access allowed to the specified resource domain.
SS$_INSFMEM	The nonpaged dynamic memory is insufficient for the operation.
SS$_IVLOCKID	The lkidadr argument specified an invalid lock ID.
SS$_IVMODE	A more privileged access mode is required.
SS$_NOMORELOCK	The caller requested a wildcard operation by specifying a value of 0 or --1 for the lkidadr argument, and $GETLKI has exhausted the locks about which it can return information to the caller; or no lkidadr argument is specified. This is an alternate success status.
SS$_NOSYSLCK	The caller attempted to acquire information about a systemwide lock and did not have the required SYSLCK privilege.
SS$_NOWORLD	The caller attempted to acquire information about a lock held by a process in another group and did not have the required WORLD privilege.

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

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	char_string
type:	character-coded text string
access:	write 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:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

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

facility	Identifies the component of the operating system
severity	Is the severity code (the low-order three bits of the condition value)
ident	Is the unique message identifier
message-text	Is the text of the message

SS$_NORMAL	The service completed successfully.
SS$_BUFFEROVF	The service completed successfully. The string returned overflowed the buffer provided and has been truncated.
SS$_INSFARG	The call arguments are insufficient.
SS$_MSGNOTFND	The service completed successfully; however, the message code cannot be found, and a default message has been returned.

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

OpenVMS usage:	function_code
type:	word (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference