HP OpenVMS Systems Documentation

Deletes a range of addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations.

Format

SYS$DELTVA inadr ,[retadr] ,[acmode]

C Prototype

int sys$deltva (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode);

Arguments

inadr

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

Starting and ending virtual addresses of the pages to be deleted. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. If the starting and ending virtual addresses are the same, a single page is deleted. The addresses are adjusted up or down to fall on CPU-specific page boundaries. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.

The $DELTVA service deletes pages starting at the address contained in the second longword of the inadr argument and ending at the address in the first longword. Thus, if you use the same address array for both the Create Virtual Address Space ($CRETVA) and the $DELTVA services, the pages are deleted in the reverse order from which they were created.

retadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Starting and ending process virtual addresses of the pages that $DELTVA has deleted. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.

acmode

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

Access mode on behalf of which the service is to be performed. The acmode argument is a longword containing the access mode.

The most privileged access mode used is the access mode of the caller. The calling process can delete pages only if those pages are owned by an access mode equal to or less privileged than the access mode of the calling process.

Description

The Delete Virtual Address Space service deletes a range of addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations. If any of the pages in the specified range have already been deleted or do not exist, the service continues as if the pages were successfully deleted.

If an error occurs while pages are being deleted, the retadr argument specifies the pages that were successfully deleted before the error occurred. If no pages are deleted, both longwords in the return address array contain the value --1.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The input address array cannot be read by the caller, or the return address array cannot be written by the caller.
SS$_NOPRIV	A page in the specified range is in the system address space.
SS$_PAGOWNVIO	A page in the specified range is owned by an access mode more privileged than the access mode of the caller.
SS$_NOSHPTS	The region ID of a shared page table region was specified.
SS$_VA_IN_USE	The existing underlying page cannot be deleted because it is associated with a buffer object.

On Alpha systems, deletes a range of virtual addresses from a process's virtual address space. Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations.

This service accepts 64-bit addresses.

Format

SYS$DELTVA_64 region_id_64 ,start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64

C Prototype

int sys$deltva_64 (struct _generic_64 *region_id_64, void *start_va_64, unsigned __int64 length_64, unsigned int acmode, void *(*(return_va_64)), unsigned __int64 *return_length_64);

Arguments

region_id_64

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The region ID associated with the region from which to address the VA space.

The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each of the three default regions in P0, P1, and P2 space.

The following region IDs are defined:

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can be specified. Also, the region ID that a virtual address is in can be obtained by calling the $GET_REGION_INFO service, specifying the VA$_REGSUM_BY_VA function.

start_va_64

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by value

The starting virtual address of the pages to be deleted. The specified address must be a CPU-specific page aligned address. If the region_id_64 argument specifies a shared page table region or if the start_va_64 argument lies within a shared page table region, the specified address must be a CPU-specific page table page aligned address.

length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

Length of the virtual address space to be deleted. The length specified must be a multiple of CPU-specific pages. If the virtual address space is being deleted from a shared page table region, the specified length must be page table page aligned or include the last page in a memory-resident section.

acmode

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

Access mode associated with the call to $DELTVA_64. The acmode argument is a longword containing the access mode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in SYS$STARLET_C.TLB define the following symbols and their values for the four access modes:

Value	Symbolic Name	Access Mode
0	PSL$C_KERNEL	Kernel
1	PSL$C_EXEC	Executive
2	PSL$C_SUPER	Supervisor
3	PSL$C_USER	User

The most privileged access mode used is the access mode of the caller. The calling process can delete pages only if those pages are owned by an access mode equal to or less privileged than the access mode of the calling process.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of the deleted virtual address range. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the $DELTVA_64 service returns the virtual address.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword into which the $DELTVA_64 service returns the length in bytes of the virtual address range deleted.

Description

The Delete Virtual Address Space service is a kernel mode service that can be called from any mode. This service deletes a range of addresses from a process's virtual address space.

Upon successful completion of the service, the deleted pages are inaccessible, and references to them cause access violations. If any of the pages in the specified range have already been deleted or do not exist, the service continues as if the pages were successfully deleted.

If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64 and return_length_64 arguments. If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully deleted before the error occurred. If no pages were deleted, the return_va_64 argument will contain the value --1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

None

Required Quota

None

Related Services

$CREATE_REGION_64, $CRETVA_64, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64, $CRMPSC_GPFN_64, $CRMPSC_PFN_64, $DELETE_REGION_64, $EXPREG_64, $MGBLSC_64, $MGBLSC_GPFN_64

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The return_va_64 argument or the return_length_64 argument cannot be written by the caller.
SS$_IVREGID	Invalid region ID specified. This condition value is returned if P0, P1, or P2 space is specified because these regions cannot be deleted, or if no region exists for the specified ID.
SS$_LEN_NOTPAGMULT	The length_64 argument is not a multiple of CPU-specific pages; or, for shared page table regions, is not a multiple of CPU-specific page table pages or does not include the last page in a memory-resident global section.
SS$_PAGNOTINREG	A page in the specified range is not within the specified region.
SS$_PAGOWNVIO	A page in the specified range is owned by an access mode more privileged than the access mode of the caller.
SS$_VA_NOTPAGALGN	The start_va_64 argument is not a CPU-specific page table page aligned address; or, for shared page table regions, is not page table page aligned.
SS$_VA_IN_USE	The existing underlying page cannot be deleted because it is associated with a buffer object.

Dequeues (unlocks) granted locks; dequeues the sublocks of a lock; or cancels an ungranted lock request. The calling process must have previously acquired the lock or queued the lock request by calling the Enqueue Lock Request ($ENQ) service.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$DEQ [lkid] ,[valblk] ,[acmode] ,[flags]

C Prototype

int sys$deq (unsigned int lkid, void *valblk, unsigned int acmode, unsigned int flags);

Arguments

lkid

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

Lock identification of the lock to be dequeued. The lkid argument specifies this lock identification.

Note that if you do not specify the lkid argument, you must specify the LCK$M_DEQALL flag in the flags argument.

When you specify the LCK$M_DEQALL flag in the flags argument, different values (or no value) for the lkid argument produce varying behavior:

• When you do not specify the lkid argument (or specify it as 0) and you do specify the LCK$M_DEQALL flag, $DEQ dequeues all locks held by the process, at access modes equal to or less privileged than the effective access mode, on all resources. The effective access mode is the least privileged of the caller's access mode and the access mode specified in the acmode argument.
• When you specify the lkid argument as a nonzero value together with the LCK$M_DEQALL flag, $DEQ dequeues all sublocks of the lock identified by lkid; it does not dequeue the lock identified by lkid. For this operation, $DEQ ignores the LCK$M_CANCEL flag if it is set. A sublock of a lock is a lock that was created when the parid argument in the call to $ENQ was specified, where parid is the lock ID of the parent lock.

If you omit the lkid argument (or specify it as 0) and the LCK$M_DEQALL flag is not set, the $DEQ service returns the invalid lock ID condition value (SS$_IVLOCKID).

valblk

OpenVMS usage:	lock_value_block
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Lock value block for the resource associated with the lock to be dequeued. The valblk argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit (on VAX systems) of the 16-byte lock value block. When you specify the LCK$M_DEQALL flag, you cannot use this argument.

When a protected write (PW) or exclusive (EX) mode lock is being dequeued and you specify a lock value block in the valblk argument, the contents of that lock value block are written to the lock value block in the lock database. Further, if the lock value block in the lock database was marked as invalid, that condition is cleared; the block becomes valid.

acmode

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

Access mode of the lock to be dequeued. The acmode argument is a longword containing the access mode.

The acmode argument is valid only if the LCK$M_DEQALL flag of the flags argument is set. The $PSLDEF macro defines the following symbols for the four access modes:

Symbol	Access Mode
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

When dequeuing locks, $DEQ maximizes the access mode of the caller and the specified acmode argument. The maximized access mode is the less privileged of the caller's access mode and the acmode argument. If you do not specify the acmode argument, $DEQ uses the caller's access mode. Only those locks with an access mode that is equal to or less than the maximized access mode are dequeued.

flags

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

Flags specifying options for the $DEQ operation. The flags argument is a longword bit mask that is the logical OR of each bit set, where each bit corresponds to an option.

Note that if you do not specify the lkid argument, you must specify the LCK$M_DEQALL flag in the flags argument.

A symbolic name for each flag bit is defined by the $LCKDEF macro. The following table describes each flag:

Flag	Description
LCK$M_DEQALL	When you specify this flag, $DEQ dequeues multiple locks, depending on the value of the lkid argument. Refer to the description of the lkid argument for details. The acmode argument is ignored if the LCK$M_DQALL flag is not set. If you specify LCK$M_DEQALL, the LCK$M_CANCEL flag, if set, is ignored.
LCK$M_CANCEL	When you specify this flag, $DEQ attempts to cancel a lock request that was queued by $ENQ. You can cancel only a waiting request. When the request is canceled, $DEQ returns the condition value SS$_NORMAL. If you attempt to cancel a granted lock, the request fails and $DEQ returns the condition value SS$_CANCELGRANT. There are two types of waiting requests that can be canceled: A request for a new lock A request to convert an existing lock When canceling a new lock request, the following action is taken: If a completion asynchronous system trap (AST) was requested, the AST is queued for delivery and SS$_ABORT is stored in the lock status block. When canceling a request to convert an existing lock, the conversion request is canceled. The existing granted lock remains unchanged. The following specific actions are taken: The blocking AST address specified for the existing granted lock is queued for delivery if the granted mode of the existing lock is blocking other waiting requests. If a completion AST was specified by the conversion request, the completion AST is queued for delivery with SS$_CANCEL status stored in the lock status block that was specified by the conversion request. If you specify the LCK$M_DEQALL flag, the LCK$M_CANCEL flag is ignored.
LCK$M_INVVALBLK	When you specify this flag, $DEQ marks the lock value block, which is maintained for the resource in the lock database, as invalid. The lock value block remains marked as invalid until it is again written to. The Description section of the $ENQ service provides additional information about lock value block invalidation. This flag is ignored if (1) the lock mode of the lock being dequeued is not protected write or exclusive, or (2) you specify the LCK$M_CANCEL flag.

Description

The Dequeue Lock Request service dequeues (unlocks) granted locks and waiting lock requests. The calling process must have previously acquired the lock or queued the lock request by calling the Enqueue Lock Request ($ENQ) service.

Action taken by the $DEQ service depends on the current state (granted or waiting) and the type of lock request (new lock or conversion request) to be dequeued.

When dequeuing a granted lock, the $DEQ service returns the condition value SS$_NORMAL and the following specific action is taken:

• Any queued blocking ASTs that have not been delivered are removed from the process's AST queues.

There are two types of waiting requests that can be dequeued:

• A request for a new lock
• A request to convert an existing lock

When dequeuing a new lock request, the $DEQ service returns the condition value SS$_NORMAL and the following specific action is taken:

• If a completion AST was requested, the completion AST is queued for delivery with SS$_ABORT stored in the lock status block.

When dequeuing a lock for which there is a conversion request waiting, the existing lock and its conversion request are dequeued. The $DEQ service returns the condition value SS$_NORMAL and the following specific actions are taken:

• If a blocking AST was queued to the process, it is removed from the process's AST queue.
• If a completion AST was specified by the conversion request, the completion AST is queued for delivery with SS$_ABORT status stored in the lock status block that was specified by the conversion request.

When a protected write (PW) or exclusive (EX) mode lock is being dequeued and you specify a lock value block in the valblk argument, the contents of that lock value block are written to the lock value block in the lock database.

If you specify the LCK$M_INVVALBLK flag in the flags argument and the lock mode of the lock being dequeued is PW or EX, the lock value block in the lock database is marked as invalid whether or not a lock value block was specified in the valblk argument.

The $DEQ, $ENQ, $ENQW, and $GETLKI services together provide the user interface to the lock management facility. For additional information about lock management, refer to the descriptions of these other services and to the OpenVMS Programming Concepts Manual.

Required Access or Privileges

None

Required Quota

None

Related Services

$ENQ, $ENQW, $GETLKI, $GETLKIW

Condition Values Returned

SS$_NORMAL	The lock was dequeued successfully.
SS$_ACCVIO	The value block specified by the valblk argument cannot be accessed by the caller.
SS$_CANCELGRANT	The LCK$M_CANCEL flag in the flags argument was specified, but the lock request that $DEQ was to cancel had already been granted.
SS$_ILLRSDM	An illegal attempt to modify a value block was made.
SS$_IVLOCKID	An invalid or nonexistent lock identification was specified or the process does not have the privilege to dequeue a lock at the specified access mode.
SS$_SUBLOCKS	The lock has sublocks and cannot be dequeued.

Returns the displayable pathname for a given I/O channel or device name. Can be used to return all displayable paths to an I/O device.

Format

SYS$DEVICE_PATH_SCAN [chan] [,devnam] ,itmlst [,contxt] [,nullarg]

C Prototype

int sys$device_path_scan (unsigned short int chan, void *devnam, void *itmlst, unsigned int *contxt, struct_generic_64 *nullarg);

Arguments

chan

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

Number of the I/O channel assigned to the device about which information is desired. The chan argument is a word containing this number.

To identify a device to $DEVICE_PATH_SCAN, you can specify either the chan or devnam parameters, but you should not specify both. If you specify both arguments, the chan argument is used.

If you specify neither chan nor devnam, $DEVICE_PATH_SCAN uses a default value of 0 for chan.

devnam

OpenVMS usage:	device_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

The name of the device about which $DEVICE_PATH_SCAN is to return path information. The devnam argument is the address of a character string descriptor pointing to this name string.

The device name string can be either a physical device name or a logical name. If the first character in the string is an underscore (_), the string is considered a physical device name; otherwise, the string is considered a logical name and logical name translation is performed until either a physical device name is found or the system default number of translations has been performed.

If the device name string contains a colon (:), the colon and the characters that follow it are ignored.

To identify a device to $DEVICE_PATH_SCAN, you can specify either the chan or devnam argument, but you should not specify both. If both arguments are specified, the chan argument is used.

If you specify neither chan nor devnam, $DEVICE_PATH_SCAN uses a default value of 0 for chan.

itmlst

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

Item list specifying which information about the device is to be returned. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a longword of 0. The following diagram depicts the format of a single item descriptor:

See the itmlst argument in the $GETDVI system service description for information on the meaning of these fields in the item list.

contxt

nullarg

Item Code

DPS$_MP_PATHNAME

When you specify DPS$_MP_PATHNAME, $DEVICE_PATH_SCAN returns the name of one of the Multipath I/O paths connecting to the device named in the devnam argument. When the value of the contxt argument is 0, the path name for the first established path will be returned. On subsequent calls, with a non-zero contxt value, the path names of the remaining available paths to the device will be returned.

In the item code, the Buffer Address field must point to the buffer that will hold the path name to be returned by the service. The Return Length Address field must be point to the buffer that will hold the return length returned by the service.

Upon completion of the command, the buffer pointed to by the Buffer Address field will hold a string identifying the requested path name. The Return Length Address field will point to the length in bytes of the path name being returned. The bytes in the path name buffer beyond the end of the path string will remain in the state they were set by the caller of the service.

The DPSDEF macro contains this item code.

Description

The Scan for Device Paths service returns I/O path information for a given I/O channel or device name. Each call to $DEVICE_PATH_SCAN will return information on a different I/O path connecting with the device specified in the chan or devnam arguments.

If the contxt argument is handled appropriately, the service will return information on the paths in the order in which they were established. On the first call, the contxt argument should be set to zero. The contxt value will be changed by the service during this call and a new value will be written into contxt and returned to the caller. The caller must use this same value in the next call to the service. Following this convention will result in a different path name being returned on each call.

Once the service has returned information on all paths to the named device, any further calls that use the final contxt value will result in SS$_NOMOREPATH status being returned.

Required Access or Privileges

None

Required Quota

None.

Related Services

$ASSIGN, $DASSGN, $DEVICE_SCAN, $GETDVI, $GETDVIW, $SET_DEVICE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The device name string descriptor, device name string, or itmlst argument cannot be read; or the buffer or return length longword cannot be written.
SS$_BADPARAM	The item list contains an invalid item code, or the buffer length field in an item descriptor specified insufficient space for the return length information.
SS$_IVCHAN	You specified an invalid channel number, that is, a channel number larger than the number of channels.
SS$_IVDEVNAM	The device name string contains invalid characters, or neither the devnam nor chan argument was specified.
SS$_NOPRIV	The specified channel is not assigned or was assigned from a more privileged access mode.
SS$_NOMOREPATH	No more device paths exist for this device.
SS$_NOSUCHDEV	The specified device does not exist on the host system.

Returns the names of all devices that match a specified set of search criteria.

Format

SYS$DEVICE_SCAN return_devnam ,retlen ,[search_devnam] ,[itmlst] ,[contxt]

C Prototype

int sys$device_scan (void *return_devnam, unsigned short int *retlen, void *search_devnam, void *itmlst, struct _generic_64 *contxt);

Arguments

return_devnam

OpenVMS usage:	char_string
type:	character-coded text string
access:	write only
mechanism:	by descriptor--fixed-length string descriptor

Buffer to receive the device name. The return_devnam argument is the address of a character string descriptor pointing to a buffer into which $DEVICE_SCAN writes the name of the first or next device that matches the specified search criteria. The maximum size of any device name is 64 bytes.

retlen

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Length of the device name string returned by $DEVICE_SCAN. The retlen argument is the address of a word into which $DEVICE_SCAN writes the length of the device name string.

search_devnam

OpenVMS usage:	device_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Name of the device for which $DEVICE_SCAN is to search. The search_devnam argument accepts the standard wildcard characters, the asterisk (*), which matches any sequence of characters, and the percent sign (%), which matches any one character. If the search_devnam argument does not include a wildcard character, an exact match is used for comparison. For example, to match all unit 0 DU devices on any controller, specify *DU%0. This string is compared to the most complete device name (DVI$_ALLDEVNAM). Only uppercase characters are accepted.

itmlst

OpenVMS usage:	item_list_3
type:	longword_unsigned
access:	read only
mechanism:	by reference

Item list specifying search criteria used to identify the device names for return by $DEVICE_SCAN. The itmlst argument is the address of a list of item descriptors, each of which describes one search criterion. The list of item descriptors is terminated by a longword of 0.

The following diagram depicts the format of a single item descriptor:

The following table defines the item descriptor fields:

contxt

Item Codes

DVS$_DEVCLASS

An input value item code that specifies, as an unsigned longword, the device class being searched. The $DCDEF macro defines these classes.

The DVS$_DEVCLASS argument is a longword containing this number; however, DVS$_DEVCLASS uses only the low-order byte of the longword.

DVS$_DEVTYPE

An input value item code that specifies, as an unsigned longword, the device type for which $DEVICE_SCAN is going to search. The $DCDEF macro defines these types.

The DVS$_DEVTYPE argument is a longword containing this number; however, DVS$_DEVTYPE uses only the low-order byte of the longword. DVS$_DEVTYPE should be used in conjunction with $DVS_DEVCLASS to specify the device type being searched for.

Description

The Scan for Devices system service returns the names of all devices that match a specified set of search criteria. The names returned by $DEVICE_SCAN can then be passed to another service; for example, $GETDVI or $MOUNT.

The device names are returned for one process per call. A context value is used to continue multiple calls to $DEVICE_SCAN.

$DEVICE_SCAN allows wildcard searches based on device names, device classes, and device types. It also provides the ability to perform a wildcard search on other device-related services.

$DEVICE_SCAN makes it possible to combine search criteria. For example, to find only RA82 devices, use the following selection criteria:

DVS$_DEVCLASS = DC$_DISK and DVS$_DEVTYPE = DT$_RA82

To find all mailboxes with MB as part of the device name (excluding mailboxes such as NLA0), use the following selection criteria:

DVS$_DEVCLASS = DC$_MAILBOX and DEVNAM = *MB*

Required Access or Privileges

None

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The search_devnam, itmlst, or contxt argument cannot be read by the caller, or the retlen, return_devnam, or contxt argument cannot be written by the caller.
SS$_BADPARAM	The contxt argument contains an invalid value, or the item list contains an invalid item code.
SS$_NOMOREDEV	No more devices match the specified search criteria.
SS$_NOSUCHDEV	The specified device does not exist on the host system.

Marks an existing permanent global section for deletion. The actual deletion of the global section takes place when all processes that have mapped the global section have deleted the mapped pages.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$DGBLSC [flags] ,gsdnam ,[ident]

C Prototype

int sys$dgblsc (unsigned int flags, void *gsdnam, struct _secid *ident);

Arguments

flags

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

Mask indicating global section characteristics. The flags argument is a longword value. A value of 0 (the default) specifies a group global section; a value of SEC$M_SYSGBL specifies a system global section; a value of SEC$M_SHMGS on an OpenVMS Galaxy system creates a shared-memory global section.

gsdnam

OpenVMS usage:	section_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 global section to be deleted. The gsdnam argument is the address of a character string descriptor pointing to this name string.

For group global sections, the operating system interprets the group UIC as part of the global section name; thus, the names of global sections are unique to UIC groups.

You can specify any name from 1 to 43 characters. All processes mapping to the same global section must specify the same name. Note that the name is case sensitive.

Use of characters valid in logical names is strongly encouraged. Valid values include alphanumeric characters, the dollar sign ($), and the underscore (_). If the name string begins with an underscore (_), the underscore is stripped and the resultant string is considered to be the actual name. Use of the colon (:) is not permitted.

Names are first subject to a logical name translation, after the application of the prefix GBL$ to the name. If the result translates, it is used as the name of the section. If the resulting name does not translate, the name specified by the caller is used as the name of the section.

Additional information on logical name translations and on section name processing is available in the OpenVMS Programming Concepts Manual.

ident

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

Identification value specifying the version number of the global section to be deleted and the matching criteria to be applied. The ident argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a quadword structure containing three fields.

The version number is in the second longword. The version number contains two fields: a minor identification in the low-order 24 bits and a major identification in the high-order 8 bits. Values for these fields can be assigned by installation convention to differentiate versions of global sections. If you specify no version number when creating a section, processes that specify a version number when mapping cannot access the global section.

The first longword specifies, in its low-order 3 bits, the matching criteria. The valid values, the symbolic names by which they can be specified, and their meanings are listed in the following table:

Value	Name	Match Criteria
0	SEC$K_MATALL	Match all versions of the section.
1	SEC$K_MATEQU	Match only if major and minor identifications match.
2	SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

If you specify no address or specify it as 0 (the default), the version number and match control fields default to 0.

Description

The Delete Global Section service marks an existing permanent global section for deletion. The actual deletion of the global section takes place when all processes that have mapped the global section have deleted the mapped pages.

After a global section has been marked for deletion, any process that attempts to map it receives the warning return status code SS$_NOSUCHSEC.

Temporary global sections are automatically deleted when the count of processes using the section goes to 0.

On VAX systems, a section located in memory that is shared by multiple processors can be marked for deletion only by a process running on the same processor that created the section.

Required Access or Privileges

Depending on the operation, the calling process might need one or more of the following privileges:

• SYSGBL privilege to delete a system global section
• PRMGBL privilege to delete a permanent global section
• PFNMAP privilege to delete a page frame section
• SHMEM privilege to delete a global section located in memory shared by multiple processors

Required Quota

None

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW

The $DGBLSC service does not unmap a global section from a process's virtual address space. To do this, the process should call the Delete Virtual Address Space ($DELTVA or $DELTVA_64) service, which deletes the pages to which the section is mapped.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The global section name or name descriptor or the section identification field cannot be read by the caller.
SS$_INTERLOCK	The bit map lock for allocating global sections from the specified shared memory is locked by another process.
SS$_IVLOGNAM	The global section name has a length of 0 or has more than 15 characters.
SS$_IVSECFLG	You set an invalid flag, reserved flag, or flag requiring a user privilege.
SS$_IVSECIDCTL	The section identification match control field is invalid.
SS$_NOPRIV	The caller does not have the privilege to delete a system global section, does not have read/write access to a group global section, or does not have the privilege to delete a global section located in memory that is shared by multiple processors.
SS$_NOSUCHSEC	The specified global section does not exist, or the identifications do not match.
SS$_NOTCREATOR	The section is in memory shared by multiple processors and was created by a process on another processor.
+SS$_SHMNOTCNCT	The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.
SS$_TOOMANYLNAM	The logical name translation of the gsdnam string exceeded the allowed depth of 10.

The Disconnect service breaks the connection between a RAB and a FAB, thereby terminating a record stream. All system resources, such as I/O buffers and data structure space, are deallocated.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Dismounts a mounted volume or volume sets.

Format

SYS$DISMOU devnam ,[flags]

C Prototype

int sys$dismou (void *devnam, unsigned int flags);

Arguments

devnam

OpenVMS usage:	device_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Device name of the device to be dismounted. The devnam argument is the address of a character string descriptor pointing to the device name string. The string can be either a physical device name or a logical name. If it is a logical name, it must translate to a physical device name.

flags

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

A longword bit vector specifying options for the dismount operation. The flags argument is a longword bit vector wherein a bit, when set, selects the corresponding option. Each bit has a symbolic name; these names are defined by the $DMTDEF macro.

The flags and their meanings are listed in the following table:

Flag	Meaning
DMT$M_ABORT	The volume is to be dismounted even if the caller did not mount the volume. If the volume was mounted with MNT$M_SHARE specified, $DISMOU dismounts the volume for all of the users who mounted it. To specify DMT$M_ABORT, the caller must: (1) have GRPNAM privilege for a group volume, (2) have SYSNAM privilege for a system volume, or (3) either own the volume or have VOLPRO privilege.
DMT$M_CLUSTER	The volume is to be dismounted clusterwide, that is, from all nodes in the OpenVMS Cluster system. $DISMOU dismounts the volume from the caller's node first and then from every other node in the existing cluster. DMT$M_CLUSTER dismounts only system or group volumes. To dismount a group volume clusterwide, the caller must have GRPNAM privilege. To dismount a system volume clusterwide, the caller must have SYSNAM privilege. DMT$M_CLUSTER has no effect if the system is not a member of a cluster. DMT$M_CLUSTER applies only to disks.
DMT$M_FORCE	If connectivity to a device has been lost and the shadow set is in mount verification, this flag causes a named shadow set member to be immediately expelled from the shadow set.
DMT$M_MINICOPY_OPTIONAL	$DISMOU takes place, regardless of whether minicopy is enabled on the disk.
DMT$M_MINICOPY_REQUIRED	$DISMOU fails if minicopy has not been enabled on the disk.
DMT$M_NOUNLOAD	Specifies that the volume is not to be physically unloaded after the dismount. If both the DMT$M_UNLOAD and DMT$M_NOUNLOAD flags are specified, the DMT$M_NOUNLOAD flag is ignored. If neither flag is specified, the volume is physically unloaded, unless the DMT$M_NOUNLOAD flag was specified on the $MOUNT system service or the /NOUNLOAD qualifier was specified on the MOUNT command when the volume was mounted.
DMT$M_OVR_CHECKS	Specifies that the volume should be dismounted without checking for open files, spooled devices, installed images, or installed swap and page files.
DMT$M_UNIT	The specified device, rather than the entire volume set, is dismounted.
DMT$M_UNLOAD	Specifies that the volume is to be physically unloaded after the dismount. If both the DMT$M_UNLOAD and DMT$M_NOUNLOAD flags are specified, the DMT$M_NOUNLOAD flag is ignored. If neither flag is specified, the volume is physically unloaded, unless the DMT$M_NOUNLOAD flag was specified on the $MOUNT system service or the /NOUNLOAD qualifier was specified on the MOUNT command when the volume was mounted.

Description

The Dismount Volume service dismounts a mounted volume or volume sets. To dismount a private volume, the caller must own the volume.

When you issue the $DISMOU service, $DISMOU removes the volume from your list of mounted volumes, deletes the logical name (if any) associated with the volume, and decrements the mount count.

If the mount count does not equal 0 after being decremented, $DISMOU does not mark the volume for dismounting (because the volume must have been mounted shared). In this case, the total effect for the issuing process is that the process is denied access to the volume and a logical name entry is deleted.

If the mount count equals 0 after being decremented, $DISMOU marks the volume for dismounting. After marking the volume for dismounting, $DISMOU waits until the volume is idle before dismounting it. A native volume is idle when no user has an open file to the volume, and a foreign volume is idle when no channels are assigned to the volume.

Native volumes are Files-11 structured disks or ANSI-structured tapes. Foreign volumes are not Files-11 or ANSI structured media.

After a volume is dismounted, nonpaged pool is returned to the system. Paged pool is also returned if you mounted the volume using the /GROUP or /SYSTEM qualifier.

If a volume is part of a Files-11 volume set and the flag bit DMT$V_UNIT is not set, the entire volume set is dismounted.

When a Files-11 volume has been marked for dismount, new channels can be assigned to the volume, but no new files can be opened.

Note that the SS$_NORMAL status code indicates only that $DISMOU has successfully performed one or more of the actions just described: decremented the mount count, marked the volume for dismount, or dismounted the volume. The only way to determine that the dismount has actually occurred is to check the device characteristics using the Get Device/Volume Information ($GETDVI) service.

By specifying the DVI$_DEVCHAR item code in a call to $GETDVI, you can learn whether a volume is mounted (it is if the DEV$V_MNT bit is set) or whether it is marked for dismounting (it is if the DEV$M_DMT bit is set). If DEV$V_MNT is clear or if DEV$M_DMT is set, the mount count is 0.

Required Access or Privileges

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

• GRPNAM privilege to dismount a volume mounted with the /GROUP qualifier
• SYSNAM privilege to dismount a volume mounted with the /SYSTEM qualifier

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The device name descriptor cannot be read or does not describe a readable device name.
SS$_DEVALLOC	The device is allocated to another process and cannot be dismounted by the caller.
SS$_DEVOFFLINE	The specified device is not available.
SS$_DEVNOTMOUNT	The specified device is not mounted.
SS$_IVDEVNAM	The device name string is not valid.
SS$_IVLOGNAM	The device logical name has a length of 0 or is longer than the allowable logical name length.
SS$_NOGRPNAM	GRPNAM privilege is required to dismount a volume mounted for groupwide access.
SS$_NOIOCHAN	No I/O channel is available. To use $DISMOU, a channel must be assigned to the volume.
SS$_NONLOCAL	The device is on a remote node.
SS$_NOSUCHDEV	The specified device does not exist.
SS$_NOSYSNAM	SYSNAM privilege is required to dismount a volume mounted for systemwide access.
SS$_NOTFILEDEV	The specified device is not file structured.

The Display service retrieves file attribute information about a file and places this information in fields in the FAB, in XABs chained to the FAB, and in a NAM block (if one is requested).

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Returns information about one or more existing proxies.

Format

SYS$DISPLAY_PROXY rem_node ,rem_user ,buffer_sizes ,proxy_node ,proxy_user ,default_user ,local_users ,flags ,[context]

C Prototype

int sys$display_proxy (void *rem_node, void *rem_user, unsigned short int buffer_sizes [4], void *proxy_node, void *proxy_user, void *default_user, unsigned int *local_users, unsigned int flags, unsigned int *context);

Arguments

rem_node

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Remote node name of the proxy about which information is being requested. The rem_node argument is the address of a character-string descriptor pointing to the remote node name string.

A remote node name consists of 1 to 1024 characters. No specific characters, format, or case are required for a remote node name string. All node names are converted to their DECnet full name unless the PRX$M_BYPASS_EXPAND flag is set with the flags argument.

Asterisk (*) and percent sign (%) wildcards are allowed for the remote node specification. If you specify wildcards for the rem_node argument, the server searches the entire proxy database for matches to the remote node and remote user you specified. If a match is found, information about the matched proxy is returned. See the Description section for additional details on retrieving information about multiple proxies.

rem_user

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Remote user name of the proxy about which information is being requested. The rem_user argument is the address of a character-string descriptor pointing to the user name string.

A remote user name consists of 1 to 32 alphanumeric characters, including dollar signs ($), underscores (_), and brackets ([ ]). Any lowercase characters specified are automatically converted to uppercase.

The rem_user argument can be specified in user identification code (UIC) format ([group, member]). Brackets are allowed only if the remote user name string specifies a UIC. Group and member are character-string representations of octal numbers with no leading zeros.

Asterisk (*) and percent sign (%) wildcards are allowed for the remote user specification. If you specify wildcards for the rem_user argument, the server searches the entire proxy database for matches to the remote node and remote user you specified. If a match is found, information about the matched proxy is returned. See the Description section for information about retrieving information about multiple proxies.

buffer_sizes

OpenVMS usage:	return length block
type:	array of 4 words (unsigned)
access:	write only
mechanism:	by reference

Array of return lengths for various input buffers. The buffer_sizes argument is the address of an array of four words with the following format:

The following table defines the buffer_sizes fields:

proxy_node

The descriptor's buffer must be 1024 bytes long to receive a node name. The length of the returned node name is specified by the proxy node length field returned in the buffer specified by the buffer_sizes argument.

proxy_user

The descriptor's buffer must be 32 bytes long to receive a user name. The length of the returned user name is specified by the proxy user length field returned in the buffer specified by the buffer_sizes argument.

default_user

The descriptor's buffer must be 32 bytes long to receive a user name. The length of the returned user name is specified in the default user length field in the buffer specified by the buffer_sizes argument.

local_users

Each element in the array is a 36-byte block with the following format:

The following table defines the local_users fields:

The buffer specified by the local_users argument must be able to contain up to 16 user name buffers; therefore, the buffer length must be 576 bytes.

The number of elements returned in the buffer is specified in the local users count field returned in the buffer specified by the buffer_sizes argument.

flags

Each flag option has a symbolic name. The $PRXDEF macro defines the following symbolic names:

context

The initial value contained in the longword pointed to by the context argument must be 0. The contents of the unsigned longword must not be changed after the service has set its value. If the contents of the buffer pointed to by the context argument are changed between calls to the $DISPLAY_PROXY service, the service will return SS$_BADCONTEXT. If the contents of the context argument are changed between calls to the $DISPLAY_PROXY service, you can change the value of the context argument back to 0 to start the search over again.

Contexts become invalid after one-half hour of non-use. This means that if you call the $DISPLAY_PROXY service with a wildcard rem_node or rem_user, and do not call the service to get the next matching record within one-half hour, the context becomes invalid. If the context has become invalid, you must start your search of the proxy database over from its beginning by resetting the context to 0.

Description

The Display Proxy Information service returns to the caller all information about a specified proxy in the proxy database.

Wildcards can be specified for the rem_node and rem_user arguments. Because $DISPLAY_PROXY can return information about only one matching proxy at a time, you must call this service repeatedly with the context argument to retrieve information about all matching proxies. $DISPLAY_PROXY returns SS$_NOMOREITEMS when information about all of the matching proxies has been returned. No proxy information is returned from the call that returns the SS$_NOMOREITEMS status.

Required Access or Privileges

The caller must have SYSPRV privilege or a UIC group less than or equal to the MAXSYSGRP system parameter.

Required Quota

None

Related Services

$ADD_PROXY, $DELETE_PROXY, $VERIFY_PROXY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The rem_node or rem_user argument cannot be read by the service; or the buffer_sizes, proxy_node, proxy_user, default_user, or local_users argument cannot be written by the service; or the context argument cannot be read or written by the service.
SS$_BADBUFLEN	The length of the rem_node, rem_user, proxy_node, proxy_user, default_user, or local_users argument was out of range.
SS$_BADCONTEXT	The context argument did not contain a 0 on the first call to the service, or the context argument's value changed between consecutive calls to the service.
SS$_NOMOREITEMS	Information about all proxies matching the specification of the rem_node and rem_user arguments has been returned by the service.
SS$_NOREADALL	The caller does not have access to the proxy database.
This service can also return any of the following messages passed from the security server, or any OpenVMS RMS error message encountered during operations on the proxy database:
SECSRV$_BADNODENAMELEN	The node name length is out of range.
SECSRV$_BADREMUSERLEN	The remote user name length is out of range.
SECSRV$_NOSUCHPROXY	The proxy specified by the rem_node and rem_user arguments does not exist in the proxy database.
SECSRV$_NOSUCHUSER	The specified local user does not exist in the proxy's local user list, or is not the proxy's default user.
SECSRV$_PROXYNOTACTIVE	Proxy processing is currently stopped. Try the request again later.
SECSRV$_SERVERNOTACTIVE	The security server is not currently active. Try the request again later.

Marks a permanent common event flag cluster for deletion.

Format

SYS$DLCEFC name

C Prototype

int sys$dlcefc (void *name);

Argument

name

OpenVMS usage:	ef_cluster_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Name of the common event flag cluster to be deleted. The name argument is the address of a character string descriptor pointing to the name of the cluster.

The names of event flag clusters are unique to UIC groups, and the UIC group number of the calling process is part of the name.

Description

The Delete Common Event Flag Cluster service marks a permanent common event flag cluster for deletion. The cluster is actually deleted when no more processes are associated with it. The $DLCEFC service does not disassociate a process from a common event flag cluster; the Disassociate Common Event Flag Cluster ($DACEFC) service does this. However, the system disassociates a process from an event flag cluster at image exit.

If the cluster has already been deleted or does not exist, the $DLCEFC service returns the status code SS$_NORMAL.

Required Access or Privileges

Delete access is required.

Required Quota

None

Related Services

$ASCEFC, $CLREF, $DACEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_IVLOGNAM	The cluster name string has a length of 0 or has more than 15 characters.
SS$_NOPRIV	The process does not have the privilege to delete a permanent common event flag cluster, or the process does not have the privilege to delete a common event flag cluster in memory shared by multiple processors.

On VAX systems, the DIGITAL Distributed Name Service (DECdns) clerk allows client applications to store resource names and addresses.

The $DNS system service completes asynchronously; that is, it returns to the client immediately after making a name service call. The status returned to the client call indicates whether a request was successfully queued to the name service.

The DIGITAL Distributed Name Service Clerk Wait ($DNSW) system service is the synchronous equivalent of $DNS. $DNSW is identical to $DNS in every way except that $DNSW returns to the caller after the operation completes.

Format

SYS$DNS [efn] ,func ,itmlst ,[dnsb] ,[astadr] ,[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 $DNS completes. The efn argument is a longword containing this number. The efn argument is optional; if not specified, event flag 0 is used.

When $DNS begins execution, it clears the event flag. Even if the service encounters an error and completes without queuing a name service request, the specified event flag is set.

func

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

Function code specifying the action that $DNS is to perform. The func argument is a longword containing this function code.

A single call to $DNS can specify one function code. Most function codes require or allow for additional information to be passed in the call with the itmlst 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 is three longwords.

The descriptors can be in any order in the item list. Each item descriptor specifies an item code. Item codes are specified as either input or output parameters. Input parameters modify functions, set context, or describe the information to be returned. Output parameters return the requested information. The item list is terminated by a longword of 0.

The item list is a standard format item list. The following figure depicts the general structure of an item descriptor:

The following table defines the item descriptor fields:

dnsb

The following figure depicts the structure of a $DNS status block:

The following table defines the status block fields:

The two qualifying status flags, DNS$V_DNSB_INOUTDIRECT and DNS$V_DNSB_OUTLINKED, are defined as follows:

• DNS$V_DNSB_INOUTDIRECT---Indicates whether the members were found in the top-level group or in one of the subgroups. The values are defined as follows:

  1: The member was found in the top-level group.
  0: The member was found in one of the subgroups of the top-level group.

• DNS$V_DNSB_OUTLINKED---If set, indicates that one or more soft links were encountered while resolving the name specified in a call.

Functions that access the DECdns server return a qualifying status. Name conversion functions do not return qualifying status.

astadr

The AST routine executes in the access mode of the caller of $DNS.

astprm

Function Codes

DNS$_ADD_REPLICA

This request adds a directory replica in the specified clearinghouse. Specify the item code DNS$_REPLICATYPE as either a secondary directory (DNS$K_SECONDARY) or a read-only directory (DNS$K_READONLY).

You must have control access to the directory being replicated and write access to the new replica's clearinghouse.

You must specify the following input value item codes:

DNS$_CLEARINGHOUSE
DNS$_DIRECTORY
DNS$_REPLICATYPE

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_ALLOW_CH

This request permits a directory to store clearinghouse objects. This request takes as input the name of a directory (DNS$_DIRECTORY).

You must have control access to the parent directory.

You must specify the following input value item code:

DNS$_DIRECTORY

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

DNS$_CREATE_DIRECTORY

This request creates a master directory in the specified clearinghouse.

You must have write or control access to the parent directory and write access to the master replica's clearinghouse.

You must specify the following input value item code:

DNS$_DIRECTORY

You can specify the following input value item codes:

DNS$_CLEARINGHOUSE
DNS$_WAIT

You can specify the following output value item code:

DNS$_OUTCTS

DNS$_CREATE_LINK

This request creates a soft link to a directory, object, soft link, or clearinghouse in the namespace. Specify the target to which the soft link points in the DNS$_TARGETNAME item code. Use the DNS$_RESOLVE_NAME function code to check the existence of the target.

You must have write or control access to the directory in which the soft link is being created.

You must specify the following input value item codes:

DNS$_LINKNAME
DNS$_TARGETNAME

You can specify the following input value item codes:

DNS$_CONF
DNS$_EXPIRETIME
DNS$_EXTENDTIME
DNS$_WAIT

You can specify the following output value item code:

DNS$_OUTCTS

DNS$_CREATE_OBJECT

This request creates an object in the namespace. Initially, the object has the attributes of DNS$CTS, DNS$UTS, DNS$Class, DNS$ClassVersion, and DNS$ACS. The name service creates the DNS$CTS, DNS$UTS, and DNS$ACS attributes. The client application supplies the DNS$Class and DNS$ClassVersion attributes. You can add attributes using the DNS$_MODIFY_ATTRIBUTE function.

The DECdns clerk cannot guarantee that an object has been created. Another DNS$_CREATE_OBJECT request could supersede the object created by your call. To verify an object creation, wait until the directory is skulked and then check to see if the requested object is present. If the value of the directory's DNS$ALLUPTO attribute is greater than the DNS$CTS of the object, your object has been successfully created.

If specified, DNS$_OUTCTS holds the creation timestamp of the newly created object.

This function code returns the following:

SS$_NORMAL
DNS$_ENTRYEXISTS
DNS$_INVALID_OBJECTNAME
DNS$_INVALID_CLASSNAME
Any condition listed in the section Condition Values Returned

You must have write access to the directory where the object will reside.

You must specify the following input value item codes:

DNS$_CLASS
DNS$_OBJECTNAME
DNS$_VERSION

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

You can specify the following output value item code:

DNS$_OUTCTS

DNS$_DELETE_DIRECTORY

This request removes a directory from the namespace.

You must have delete access to the directory being deleted and write, control, or delete access to the parent directory.

You must specify the following input value item code:

DNS$_DIRECTORY

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

DNS$_DELETE_OBJECT

This request removes the specified object from the namespace.

This function code returns the following:

SS$_NORMAL
DNS$_INVALID_OBJECTNAME
Any condition listed in the section Condition Values Returned

You must have delete access to the object.

You must specify the following input value item code:

DNS$_OBJECTNAME

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_DISALLOW_CH

This request prevents a directory from storing clearinghouse objects. This request takes as input the name of a directory (DNS$_DIRECTORY).

You must have control access to the parent directory, and read or control access to any child directories.

You must specify the following input value item code:

DNS$_DIRECTORY

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

DNS$_ENUMERATE_ATTRIBUTES

This request returns a set of attribute names in DNS$_OUTATTRIBUTESET that are associated with the directory, object, soft link, or clearinghouse. Specify the entry type in the DNS$_LOOKINGFOR item code. The function returns either DNS$K_SET or DNS$K_SINGLE along with the set of attribute names.

To manipulate the attribute names returned by this call, you should use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine.

The DECdns clerk enumerates attributes in alphabetical order. A return status of DNS$_MOREDATA implies that not all attributes have been enumerated. You should make further calls, setting DNS$_CONTEXTVARNAME to the last attribute in the set returned, until the procedure returns SS$_NORMAL.

This function code returns the following:

SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_CONTEXTNAME
Any condition listed in the section Condition Values Returned

You must have read access to the directory, object, soft link, or clearinghouse.

You must specify the following input value item codes:

DNS$_ENTRY
DNS$_LOOKINGFOR

You must specify the following output value item code:

DNS$_OUTATTRIBUTESET

You can specify the following input value item codes:

DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_WAIT

You can specify the following output value item code:

DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_ENUMERATE_CHILDREN

This request takes as input a directory name with an optional simple name that uses a wildcard. The DECdns clerk matches the input against child directory entries in the specified directory.

The DECdns clerk returns a set of simple names of child directories in the target directory that match the name with the wildcard. A null set is returned when there is no match or the directory has no child directories.

To manipulate the values returned by this call, you should use the DNS$REMOVE_FIRST_SET_VALUE run-time routine. The value returned is a simple name.

The clerk enumerates child directories in alphabetical order. If the call returns DNS$_MOREDATA, not all child directories have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last child directory in the set returned, until the procedure returns SS$_NORMAL. Subsequent calls return the child directories, starting with the directory specified in DNS$_CONTEXTVARNAME and continuing in alphabetical order.

This function code returns the following:

SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME

You must have read access to the parent directory.

You must specify the following input value item code:

DNS$_DIRECTORY

You must specify the following output value item code:

DNS$_OUTCHILDREN

You can specify the following input value item codes:

DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_WAIT
DNS$_WILDCARD

You can specify the following output value item code:

DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_ENUMERATE_OBJECTS

This request takes as input the directory name, a simple name that can use a wildcard, and a class name that uses a wildcard. The DECdns clerk matches these against objects in the directory. If a wildcard and class filter are not specified, all objects in the directory are returned.

The function returns (in DNS$_OUTOBJECTS) a set of simple names of object entries in the directory that match the name with the wildcard. The function also returns the class of the object entries, if specified with DNS$_RETURNCLASS. If no object entries match the wildcard or the directory contains no object entries, a null set is returned.

To manipulate the values returned by this call, you should use the DNS$REMOVE_FIRST_SET_VALUE run-time routine. The value returned is a simple name structure.

The clerk enumerates objects in alphabetical order. If the call returns DNS$_MOREDATA, not all objects have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last object in the set returned, until the procedure returns SS$_NORMAL. If the class filter is specified, only those objects of the specified classes are returned.

This function code returns the following:

SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME
DNS$_INVALID_CLASSNAME

You must have read access to the directory.

You must specify the following input value item code:

DNS$_DIRECTORY

You must specify the following output value item code:

DNS$_OUTOBJECTS

You can specify the following input value item codes:

DNS$_CLASSFILTER
DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_RETURNCLASS
DNS$_WAIT
DNS$_WILDCARD

You can specify the following output value item code:

DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_ENUMERATE_SOFTLINKS

This request takes as input the name of a directory and a wildcarded simple name. The DECdns clerk matches these against soft links in the directory. It returns (in DNS$_OUTSOFTLINKS) a set consisting of simple names of soft links in the directory that match the wildcarded name. If no soft link entries match the wildcard or the directory contains no soft links, a null set is returned.

If no wildcard is specified, then all soft links in the directory are returned.

To manipulate the values returned by this call, use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The value returned is a simple name.

The clerk enumerates soft links in alphabetical order. If the call returns DNS$_MOREDATA, not all matching soft links have been enumerated and the client should make further calls, setting DNS$_CONTEXTVARNAME to the last soft link in the set returned, until the procedure returns SS$_NORMAL.

This function code returns the following:

SS$_NORMAL
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME

You must have read access to the directory.

You must specify the following input value item code:

DNS$_DIRECTORY

You must specify the following output value item code:

DNS$_OUTSOFTLINKS

You can specify the following input value item codes:

DNS$_CONF
DNS$_CONTEXTVARNAME
DNS$_WAIT
DNS$_WILDCARD

You can specify the following output value item code:

DNS$_CONTEXTVARNAME

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_FULL_OPAQUE_TO_STRING

This request converts a full name in opaque format to its equivalent in string format. To prevent the namespace nickname from being included in the string name, set the byte referred to by DNS$_SUPPRESS_NSNAME to 1.

This function code returns the following:

SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:

DNS$_FROMFULLNAME

You must specify the following output value item code:

DNS$_TOSTRINGNAME

You can specify the following input value item code:

DNS$_SUPPRESS_NSNAME

DNS$_MODIFY_ATTRIBUTE

This request applies one update to the specified entry in the namespace. The update operations are as follows:

• Add or remove an attribute.
• Add or remove an attribute value from either a single-valued attribute or a set-valued attribute.

To add a value to a single-valued or set-valued attribute, specify a value in the DNS$_MODVALUE item code. If you do not specify a value for a single-valued attribute, you receive the error DNS$_INVALIDUPDATE. Single-valued attributes cannot exist without a value.

If you do not specify a value for a set-valued attribute, the clerk creates the attribute with an empty set.

To delete an attribute value, use the DNS$_MODVALUE item code to remove the specified value from an attribute set. If you do not specify the item code, the name service removes the attribute and all its values.

This function code returns the following:

SS$_NORMAL
DNS$_WRONGATTRIBUTETYPE
DNS$_INVALIDUPDATE
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME

You must have write or delete access to the directory, object, soft link, or clearinghouse whose attribute is being modified, depending on whether the operation adds or removes the attribute.

You must specify the following input value item codes:

DNS$_ATTRIBUTENAME
DNS$_ATTRIBUTETYPE
DNS$_ENTRY
DNS$_LOOKINGFOR
DNS$_MODOPERATION

You can specify the following input value item codes:

DNS$_CONF
DNS$_MODVALUE
DNS$_WAIT

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_NEW_EPOCH

This request reconstructs an entire replica set of a directory and synchronizes the copies to recover as much of the original directory state as possible. You can also use the function to change a replica type for configuration management purposes.

This request takes as input the full name of a clearinghouse (DNS$_CLEARINGHOUSE) and directory (DNS$_DIRECTORY). Specify, optionally, the full names of clearinghouses in which to store secondary and read-only replicas (DNS$_SECCHSET and DNS$_READCHSET).

You must have control access to the parent directory and write access to each clearinghouse for which the replica type will be changed from its current value to a new value.

You must specify the following input value item codes:

DNS$_CLEARINGHOUSE
DNS$_DIRECTORY

You can specify the following input value item codes:

DNS$_READCHSET
DNS$_SECCHSET

DNS$_PARSE_FULLNAME_STRING

This request takes a full name in string format and converts it to its equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR item code, the clerk examines the name specified in DNS$_FROMSTRINGNAME for invalid characters. The buffer returns the address of the character in the name that immediately follows a valid DECdns name.

This function code returns the following:

SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:

DNS$_FROMSTRINGNAME

You must specify the following output value item code:

DNS$_TOFULLNAME

You can specify the following input value item code:

DNS$_NEXTCHAR_PTR

DNS$_PARSE_SIMPLENAME_STRING

This request takes a simple name in string format and converts it to its equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR item code, the clerk examines the name specified in DNS$_FROMSTRINGNAME for invalid characters. The buffer returns the address of the character in that name that immediately follows a valid DECdns name.

This function code returns the following:

SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:

DNS$_FROMSTRINGNAME

You must specify the following output value item code:

DNS$_TOSIMPLENAME

You can specify the following input value item code:

DNS$_NEXTCHAR_PTR

DNS$_READ_ATTRIBUTE

This request returns (in DNS$_OUTVALSET) a set whose members are the values of the specified attribute.

To manipulate the values returned by this call, use the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The run-time library routine returns the value of a single-valued attribute or the first value from a set-valued attribute. The contents of DNS$_OUTVALSET are passed to DNS$REMOVE_FIRST_SET_VALUE, and the routine returns the value of the attribute.

The attribute values are returned in the order in which they were created. If the call returns DNS$_MOREDATA, not all of the set members have been returned. The client application can make further calls, setting DNS$_CONTEXTVARTIME to the timestamp of the last attribute in the set returned, until the procedure returns SS$_NORMAL.

If the client sets the DNS$_MAYBEMORE item code to 1, the name service attempts to make subsequent DNS$_READ_ATTRIBUTE calls for the same value more efficient.

This function code returns the following:

SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME

You must have read access to the object whose attribute is to be read.

You must specify the following input value item codes:

DNS$_ATTRIBUTENAME
DNS$_ENTRY
DNS$_LOOKINGFOR

You must specify the following output value item code:

DNS$_OUTVALSET

You can specify the following input value item codes:

DNS$_CONF
DNS$_CONTEXTVARTIME
DNS$_MAYBEMORE
DNS$_WAIT

You can specify the following output value item code:

DNS$_CONTEXTVARTIME

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_REMOVE_LINK

This request deletes a soft link from the namespace. Only the soft link is deleted. Any DECdns name that is referenced by the soft link remains unaffected by the operation.

You must have delete access to the soft link, or delete or control access to its parent directory.

You must specify the following input value item code:

DNS$_LINKNAME

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

DNS$_REMOVE_REPLICA

This request removes the specified replica of a directory.

You must have control access to the replica being removed and write access to the replica's clearinghouse.

You must specify the following input value item codes:

DNS$_CLEARINGHOUSE
DNS$_DIRECTORY

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

DNS$_RESOLVE_NAME

This request follows a chain of soft links to its target. The function returns the full name of the target.

Applications that maintain their own databases of opaque DECdns names should use DNS$_RESOLVE_NAME any time they receive the qualifying status DNS$V_DNSB_OUTLINKED. The qualifying status indicates that a soft link was followed to make the request to the DECdns server. After receiving the resolved name, the application should store it, so future references to the name do not incur the overhead of following a soft link.

If the application provides a name that does not contain any soft links, DNS$_NOTLINKED status is returned. If the target of any of the chain of soft links followed does not exist, the DNS$_DANGLINGLINK status is returned. To obtain the target of any particular soft link, use the DNS$_READ_ATTRIBUTE function with DNS$_LOOKINGFOR set to DNS$K_SOFTLINK and request the attribute DNS$LINKTARGET. This can be useful in discovering which link in a chain does not point to an existing target. If the DECdns clerk detects a loop, it returns DNS$_POSSIBLECYCLE status.

This function code returns the following:

SS$_NORMAL
DNS$_INVALID_LINKNAME
DNS$_NOTLINKED
DNS$_POSSIBLECYCLE

You must have read access to each of the soft links in the chain.

You must specify the following input value item code:

DNS$_LINKNAME

You must specify the following output value item code:

DNS$_OUTNAME

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_SIMPLE_OPAQUE_TO_STRING

This request takes a simple name in opaque format and converts it to its equivalent in string format.

This function code returns the following:

SS$_NORMAL
DNS$_INVALIDNAME

You must specify the following input value item code:

DNS$_FROMSIMPLENAME

You must specify the following output value item code:

DNS$_TOSTRINGNAME

DNS$_SKULK

This request attempts to ensure that all replicas of the specified directory have absorbed all updates applied to any replica prior to the time the skulk began. Successful update of the replica set requires all replicas to be available for an extended time.

You must have control access to the directory being skulked.

You must specify the following input value item code:

DNS$_DIRECTORY

DNS$_TEST_ATTRIBUTE

This request tests an object for the presence of a particular attribute value. This function returns DNS$_TRUE in the $DNS status block if the specified attribute has one of the following characteristics:

• It is a single-valued attribute and its value matches the specified value.
• It is a set-valued attribute and the attribute contains the specified value as one of its members.

If the attribute is not present or if the specified attribute does not exist, the function returns DNS$_FALSE in the $DNS status block.

This function code returns the following:

DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME

You must have test or read access to the directory, object, soft link, or clearinghouse whose attribute is to be tested.

You must specify the following input value item codes:

DNS$_ATTRIBUTENAME
DNS$_ENTRY
DNS$_LOOKINGFOR
DNS$_VALUE

You can specify the following input value item codes:

DNS$_CONF
DNS$_WAIT

$DNS returns the following qualifying status:

DNS$V_DNSB_OUTLINKED

DNS$_TEST_GROUP

This request tests a group object for a particular member. It returns DNS$_TRUE in the $DNS status block if the specified member is a member of the specified group (or a subgroup thereof), and DNS$_FALSE otherwise. If the clerk searches a subgroup and one or more of the subgroups is unavailable, the clerk returns the status encountered in trying to access that group.

The DNS$_INOUTDIRECT argument, on input, controls the scope of the search. If you set this item code to 1, the clerk searches only the top-level group. If you set it to 0, the clerk searches all of the subgroups. On output, the clerk returns a 1 in the DNS$V_DNSB_INOUTDIRECT qualifying status if the member was found in the top-level group; it returns a 0 if the member was found in a subgroup.

This function code returns the following:

SS$_NORMAL
DNS$_NOTAGROUP
DNS$_INVALID_GROUPNAME
DNS$_INVALID_MEMBERNAME

You must have test or read access to each of the groups being tested or control access to their respective directories.

You must specify the following input value item codes:

DNS$_GROUP
DNS$_MEMBER

You can specify the following input value item codes:

DNS$_CONF
DNS$_INOUTDIRECT
DNS$_WAIT

$DNS returns the following qualifying status:

DNS$V_DNSB_INOUTDIRECT
DNS$V_DNSB_OUTLINKED

This section describes each item code.

DNS$_ATTRIBUTENAME

The DNS$_ATTRIBUTENAME item code specifies the opaque simple name of an attribute. An attribute name cannot be longer than 31 characters.

DNS$_ATTRIBUTETYPE

The DNS$_ATTRIBUTETYPE item code specifies whether an attribute is set valued (DNS$K_SET) or single valued (DNS$K_SINGLE).

DNS$_CLASS

The DNS$_CLASS item code specifies the DNS$Class attribute of an object for the $DNS function DNS$_CREATE_OBJECT. DNS$_CLASS is an opaque simple name.

DNS$_CLASSFILTER

DNS$_CLASSFILTER specifies a filter that limits the scope of an enumeration to those objects belonging to a certain class or group of classes. DNS$_CLASSFILTER is used by the $DNS function DNS$_ENUMERATE_OBJECTS. DNS$_CLASSFILTER is an opaque simple name, which can contain a wildcard (either the asterisk or question mark).

DNS$_CLASSFILTER is optional. A wildcard simple name using an asterisk (*) is used by default, meaning that objects of all classes are enumerated.

DNS$_CLEARINGHOUSE

DNS$_CLEARINGHOUSE specifies the clearinghouse in which the directory will be added or removed. DNS$_CLEARINGHOUSE is an opaque full name.

DNS$_CONF

DNS$_CONF specifies for $DNS whether to use the clerk's cache or a DECdns server to complete the request. DNS$_CONF is 1 byte long and can take one of the following values:

Confidence Level	Description
DNS$K_LOW	On read requests, services the DECdns request from the clerk's cache. On create or modify requests, services the request from a master or secondary directory.
DNS$K_MEDIUM	Bypasses any cached information and services the request directly from a DECdns server.
DNS$K_HIGH	Services the request from the master directory.

DNS$_CONF is optional; if it is not specified, the DECdns clerk assumes a value of DNS$K_LOW.

DNS$_CONTEXTVARNAME

DNS$_CONTEXTVARNAME specifies and returns a context for the enumeration functions. On input, specify null to set the initial context. On output, DNS$_CONTEXTVARNAME returns the opaque simple name of the last item enumerated.

DNS$_CONTEXTVARNAME is optional. If you do not specify or you specify a null value for the context variable item, the clerk returns the results from the beginning of the set. To restart an enumeration where it left off, specify the last value returned in DNS$_CONTEXTVARNAME.

DNS$_CONTEXTVARTIME

DNS$_CONTEXTVARTIME specifies and returns a timestamp for the DNS$_READ_ATTRIBUTE function. On input, specify a timestamp to set up the context for reading attributes. On output, DNS$_CONTEXTVARNAME returns the timestamp of the last item read.

DNS$_CONTEXTVARTIME is optional. If you do not specify or you specify a null value for the context variable item, the clerk returns the results from the beginning of the set. To restart a read operation where it left off, specify the last value returned in DNS$CONTEXTVARTIME.

DNS$_DIRECTORY

DNS$_DIRECTORY specifies the directory in which the child directories, soft links, or objects to be enumerated reside. DNS$_DIRECTORY is an opaque full name.

DNS$_ENTRY

DNS$_ENTRY specifies the opaque full name of an object, soft link, directory, or clearinghouse in the namespace.

DNS$_EXPIRETIME

DNS$_EXPIRETIME specifies the absolute time when the soft link will expire. The clerk deletes the soft link at the expiration time. If this item code is a null value, the clerk neither checks nor deletes the link.

DNS$_EXTENDTIME

DNS$_EXTENDTIME specifies an extension factor to be added to the absolute time if the soft link still exists. A new expiration time is created by adding the expiration time and the extend time together.

DNS$_FROMFULLNAME

DNS$_FROMFULLNAME specifies for the DNS$_FULL_OPAQUE_TO_STRING function the opaque full name that is to be converted into string format.

DNS$_FROMSIMPLENAME

DNS$_FROMSIMPLENAME specifies for the DNS$_SIMPLE_OPAQUE_TO_STRING function the opaque simple name that is to be converted into string format.

DNS$_FROMSTRINGNAME

DNS$_FROMSTRINGNAME specifies, in string format, a simple or full name that is to be converted to opaque format for the parse functions DNS$_PARSE_FULLNAME_STRING and DNS$_PARSE_SIMPLENAME_STRING.

DNS$_GROUP

DNS$_GROUP specifies for the DNS$_TEST_GROUP function the opaque full name of the group that is to be tested. DNS$_GROUP must be the name of a group object.

DNS$_INOUTDIRECT

DNS$_INOUTDIRECT specifies a value that controls the scope of a test for group membership.

Value	Definition
1	Tests the top-level group specified by the DNS$_GROUP item (the default)
0	Tests all subgroups of the group named in DNS$_GROUP

DNS$_INOUTDIRECT is a single-byte value.

DNS$_LINKNAME

DNS$_LINKNAME specifies the opaque full name of a soft link.

DNS$_LOOKINGFOR

DNS$_LOOKINGFOR specifies the type of entry in the namespace on which the call is to operate. DNS$_LOOKINGFOR can take one of the following values:

• DNS$K_DIRECTORY
• DNS$K_OBJECT
• DNS$K_CHILDDIRECTORY
• DNS$K_SOFTLINK
• DNS$K_CLEARINGHOUSE

DNS$_MAYBEMORE

DNS$_MAYBEMORE is used with the DNS$_READ_ATTRIBUTE function to indicate that the results of the read operation are to be cached. This is a single-byte item.

When this item is set to 1, the clerk returns all of the entry's attributes in the return buffer. The clerk caches all of this information to make later lookups of attribute information for the same entry quicker and more efficient.

If you do not specify this item, only the requested information is returned.

DNS$_MEMBER

DNS$_MEMBER specifies for the DNS$_TEST_GROUP function of $DNS the opaque full name of a member that is to be tested for inclusion within a given group.

DNS$_MODOPERATION

DNS$_MODOPERATION specifies for the DNS$_MODIFY_ATTRIBUTE function the type of operation that is to take place. There are two types of modifications: adding an attribute or deleting an attribute. To add an attribute, specify DNS$K_PRESENT. To delete an attribute, specify DNS$K_ABSENT.

DNS$_MODVALUE

DNS$_MODVALUE specifies for the DNS$_MODIFY_ATTRIBUTE function the value that is to be added to or deleted from an attribute. The structure of this value is dependent on the application.

DNS$_MODVALUE is an optional argument that affects the overall operation of the DNS$_MODIFY_ATTRIBUTE function. Note that the DNS$_MODVALUE item code must be specified to add a single-valued attribute. You can specify a null value for a set-valued attribute. (See the DNS$_MODIFY_ATTRIBUTE item code description for more information.)

DNS$_NEXTCHAR_PTR

DNS$_NEXTCHAR_PTR is an optional item code that can be used with the parse functions DNS$_PARSE_FULLNAME_STRING and DNS$_PARSE_SIMPLENAME_STRING to return the address of an invalid character that immediately follows a valid DECdns name. This option is most useful when applications are parsing command line strings.

Without this item code, the parse functions return an error if any portion of the name string is invalid.

DNS$_OBJECTNAME

DNS$_OBJECTNAME specifies the opaque full name of an object.

DNS$_OUTATTRIBUTESET

DNS$_OUTATTRIBUTESET returns a set of enumerated attribute names. This item code is used with the DNS$_ENUMERATE_ATTRIBUTES functions. The item code returns either DNS$K_SET or DNS$K_SINGLE along with the set of attribute names.

The names returned in this set can be extracted from the buffer with the DNS$REMOVE_FIRST_SET_VALUE routine. The resulting values are contained in the $DNSATTRSPECDEF structure. This 1-byte structure indicates whether an attribute is set-valued or single-valued followed by an opaque simple name.

DNS$_OUTCHILDREN

DNS$_OUTCHILDREN returns the set of opaque simple names enumerated by the DNS$_ENUMERATE_CHILDREN function.

You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. These values are the opaque simple names of the child directories found in the parent directory.

DNS$_OUTCTS

DNS$_OUTCTS returns the creation timestamp (CTS) that the specified entry received when it was created. This item code is optional and can be used by the $DNS create functions.

DNS$_OUTNAME

DNS$_OUTNAME returns the opaque full name of the target pointed to by a soft link. This item code is used with the DNS$_RESOLVE_NAME function.

DNS$_OUTOBJECTS

DNS$_OUTOBJECTS returns the set of opaque simple names enumerated by the DNS$_ENUMERATE_OBJECTS function.

Each object name is followed by the object's class if you specify the DNS$_RETURNCLASS item code on input. The object's class is the value of the DNS$Class attribute.

You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The resulting values are the opaque simple names of the objects found in the directory.

DNS$_OUTSOFTLINKS

DNS$_OUTSOFTLINKS returns the set of opaque simple names enumerated by the DNS$_ENUMERATE_SOFTLINKS function.

You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The resulting values are the opaque simple names of the soft links found in the directory.

DNS$_OUTVALSET

DNS$_OUTVALSET returns for the DNS$_READ_ATTRIBUTE function a set of values for the given attribute.

You can extract the values resulting from the enumeration using the DNS$REMOVE_FIRST_SET_VALUE run-time library routine. The extracted values are the values of the attribute.

DNS$_READCHSET

DNS$_READCHSET specifies the names of clearinghouses that contain read-only replicas of the directory being reconstructed with DNS$_NEW_EPOCH.

DNS$_REPLICATYPE

DNS$_REPLICATYPE specifies the type of directory replica being added in the specified clearinghouse. You can add a secondary replica (DNS$K_SECONDARY) or a read-only replica (DNS$K_READONLY).

DNS$_RETURNCLASS

DNS$_RETURNCLASS specifies that the class of object entries enumerated with the DNS$_ENUMERATE_OBJECTS function should be returned along with the object names in the DNS$_OUTOBJECTS item code. The object's class is the value of the DNS$Class attribute.

DNS$_SECCHSET

DNS$_SECCHSET specifies the names of clearinghouses that contain secondary replicas of the directory being reconstructed with DNS$_NEW_EPOCH.

DNS$_SUPPRESS_NSNAME

DNS$_SUPPRESS_NSNAME specifies that the leading namespace name should not be returned in the converted full name string. This item code is used by the DNS$_FULL_OPAQUE_TO_STRING function. This is an optional single-byte value.

A value of 1 suppresses the leading namespace name in the resulting full name string.

DNS$_TARGETNAME

DNS$_TARGETNAME specifies the name of an existing entry in the namespace to which the soft link will point. This item code is used by the DNS$_CREATE_LINK function.

DNS$_TOFULLNAME

DNS$_TOFULLNAME returns for the DNS$_PARSE_FULLNAME_STRING function the address of a buffer that contains the resulting opaque full name.

DNS$_TOSIMPLENAME

DNS$_TOSIMPLENAME specifies for the DNS$_PARSE_SIMPLENAME_STRING function the address of a buffer that will contain the resulting opaque simple name.

DNS$_TOSTRINGNAME

DNS$_TOSTRINGNAME returns the string name resulting from one of the conversion functions: DNS$_FULL_OPAQUE_TO_STRING or DNS$_SIMPLE_OPAQUE_TO_STRING. DNS$_TOSTRINGNAME has the following structure:

[NS_name:] [.] Namestring [.Namestring]

• NS_name, if present, is a local system representation of the namespace creation timestamp (NSCTS), the unique identifier of the DECdns server. The DECdns clerk supplies a namespace name (node-name_NS) if the value is omitted.
• Namestring represents a simple name component. Multiple simple names are separated by periods.

DNS$_VALUE

DNS$_VALUE specifies for the DNS$_TEST_ATTRIBUTE function the value that is to be tested. This item contains the address of a buffer holding the value.

DNS$_VERSION

DNS$_VERSION specifies the DNS$ClassVersion attribute for the DNS$_CREATE_OBJECT function. This is a 2-byte structure: the first byte contains the major version number, the second contains the minor version number.

DNS$_WAIT

DNS$_WAIT enables the client to specify a timeout value to wait for a call to complete. If the timeout expires, the call returns either DNS$K_TIMEOUTNOTDONE or DNS$K_TIMEOUTMAYBEDONE, depending on whether the namespace was updated by the incomplete operation.

The parameter is optional; if it is not specified, a default timeout value of 30 seconds is assumed.

DNS$_WILDCARD

DNS$_WILDCARD is an optional item code that specifies to the enumeration functions of $DNS the opaque simple name used to limit the scope of the enumeration. (The simple name does not have to use a wildcard.) Only those simple names that match the wildcard are returned by the enumeration.

Table SYS-26 provides a summary of the data types for $DNS item codes. The data types define the encoding of each item list element.

Description

The $DNS system service provides a low-level interface between an application (client) and DECdns. The DECdns clerk interface is used to create, delete, modify, and retrieve DECdns names in a namespace.

A single system service call supports the DECdns clerk. It has two main parameters:

• A function code identifying the specific service to perform
• An item list specifying all the parameters for the required function

The use of this item list is similar to that of other system services that use a single item list for both input and output operations.

The $DNS system service performs DECnet I/O on behalf of the DECdns client. It requires system dynamic memory to construct a database to queue the I/O request and might require additional memory on a device-dependent basis.

In addition to the system services, DECdns provides a set of callable run-time library routines. You can use the clerk run-time library routines to manipulate output from the system service and to write data that can be specified in a system service function code.

For further information, refer to the OpenVMS Programming Concepts Manual.

Required Access or Privileges

None

Required Quota

• The buffered I/O byte count (BYTLM) quota for the process
• The quota for buffered I/O limit (BIOLM) or direct I/O limit (DIOLM) for the process
• The AST limit (ASTLM) quota, if an AST service routine is specified, for the process

Related Services

$DNSW

Condition Values Returned

SS$_NORMAL	Normal completion of the request.
SS$_BADPARAM	Either an item code in the item list is out of range or the item list contains more than the maximum allowable number of items.

Condition Values Returned in the $DNS Status Block

On VAX systems, is the client interface to the DIGITAL Distributed Name Service.

The $DNSW service completes synchronously; that is, it returns to the caller after the operation completes.

For asynchronous completion, use the $DNS service, which returns to the caller immediately after making a name service call. The return status to the client call indicates whether a request was successfully queued to the name service.

In all other respects, $DNSW is identical to $DNS. Refer to the $DNS description for complete information about the $DNSW service.

Format

SYS$DNSW [efn] ,func ,itmlst [,dnsb] [,astadr] [,astprm]

Removes a branch from a transaction and returns the outcome of the transaction.

Format

SYS$END_BRANCH [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,bid

C Prototype

int sys$end_branch (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid [4], unsigned int bid [4]);

Arguments

efn

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

Number of the event flag set when the service completes. If this argument is omitted, event flag 0 is used.

flags

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

Flags specifying options for the service. The flags argument is a longword bit mask in which each bit corresponds to an option flag. The $DDTMDEF macro defines symbolic names for these option flags, described in Table SYS-27. All undefined bits must be 0. If this argument is omitted, no flags are used.

Table SYS-27 $END_BRANCH Option Flags

Flag Name	Description
DDTM$M_SYNC	Specifies successful synchronous completion by returning SS$_SYNCH. When SS$_SYNCH is returned, the AST routine is not called, the event flag is not set, and the I/O status block is not filled in.
DDTM$M_NOWAIT	Indicates that the service should return to the caller without waiting for final cleanup. Note that $END_BRANCHW with the DDTM$M_NOWAIT flag set is not equivalent to $END_BRANCH. The latter returns when the operation has been queued. The former does not return until the operation has been initiated. The full range of status values may be returned from a nowait call.

iosb

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

The I/O status block in which the following information is returned:

• The completion status of the service. This is returned as a condition value. See the Condition Values Returned section for more information.
• The outcome of the transaction. If the service completes successfully, the outcome of the transaction is commit. If it returns SS$_ABORT, the outcome of the transaction is abort.
• An abort reason code that gives one reason why the transaction aborted, if the completion status of the service is SS$_ABORT. The $DDTMMSGDEF macro defines symbolic names for these abort reason codes. See $ACK_EVENT for a list of the codes that are currently defined.

The following diagram shows the structure of the I/O status block:

astadr

astprm

tid

bid

Description

The $END_BRANCH system service:

• Removes the specified branch from the specified transaction.
• Returns the outcome of the specified transaction.

If $END_BRANCH completes successfully, the outcome of the transaction is commit. If it returns SS$_ABORT, the outcome is abort.

Preconditions for the successful completion of $END_BRANCH are:

• The calling process must contain the specified branch of the specified transaction.
• The specified branch must be a synchronized branch.
• The access mode of the caller must be the same as or more privileged than that of any branch of the specified transaction in this process. (See $START_BRANCH and $START_TRANS.)

$END_BRANCH may fail for the following reasons:

• Preconditions were not met.
• An abort event has occurred for the transaction.

Postconditions on successful completion of $END_BRANCH are described in Table SYS-28:

Table SYS-28 Postconditions When$END_BRANCH Completes Successfully

Postcondition	Meaning
The branch that started the transaction has initiated a call to $END_TRANS.	The completion of $END_BRANCH is delayed until this occurs. If the transaction was not started on the local node, the successful completion of $END_BRANCH may be indefinitely postponed by network failure.
Every other authorized and synchronized branch of the transaction has initiated a call to $END_BRANCH.	The completion of $END_BRANCH is delayed until this occurs.
The transaction is ended.	The result is that: The TID of the transaction is invalid. Calls to any DECdtm system services except $GETDTI and $SETDTI that pass that TID will fail, and calls to resource managers that pass that TID will fail. The transaction no longer has any application or RM participants on the local node. All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final "cleanup" acknowledgments).
The outcome of the transaction is commit.	All the transaction operations that completed successfully before $END_TRANS was called will take effect; that is, the effects of these operations will be made permanent. Operations by any unauthorized branches will be aborted. (An unauthorized branch is one without a matching $ADD_BRANCH.)
DECdtm quotas are returned.	All quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process.	If the transaction was the default transaction of the calling process, then it is now no longer the default.

Postconditions on completion with the SS$_ABORT error are listed in Table SYS-29. $END_BRANCH does not complete with this error until all branches on the local node have been removed from the transaction. Thus this call to $END_BRANCH cannot complete with the SS$_ABORT error until after every authorized and synchronized branch on the local node has initiated a call to $END_TRANS, $END_BRANCH, or $ABORT_TRANS.

Table SYS-29 Postconditions When$END_BRANCH Completes with the SS$_ABORT Error

Postcondition	Meaning
The transaction is ended.	If DDTM$M_NOWAIT is clear: The TID of the transaction is invalid. Calls to any DECdtm system services except $GETDTI and $SETDTI that pass that TID will fail, and calls to resource managers that pass that TID will fail. The transaction no longer has any application or RM participants on the local node. All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final cleanup acknowledgments).
The outcome of the transaction is abort.	None of the operations of the transaction will ever take effect. The I/O status block contains one reason why the transaction was aborted. If there are multiple reasons for the transaction aborting, the DECdtm transaction manager returns one of the reasons in the I/O status block. It may return different reasons to different branches in the transaction. For example, if the transaction timeout expires and a communications link fails, then either the DDTM$_TIMEOUT or DDTM$_COMM_FAIL abort reason code may be returned.
DECdtm quotas are returned.	If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process.	If DDTM$M_NOWAIT is clear and the transaction was the default transaction of the calling process, then it is no longer the default.

There is also a wait form of the service, $END_BRANCHW.

Required Privileges

None

Required Quotas

ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL	If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.
SS$_SYNCH	The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ABORT	The transaction aborted. See the abort reason code returned in the I/O status block for one reason why the transaction aborted.
SS$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	Either the options flags were invalid or the tid argument was omitted but the bid argument was not zero.
SS$_BRANCHENDED	Either the calling process had already called $END_BRANCH or $ABORT_TRANS specifying that BID, or the branch was unsynchronized.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_ILLEFC	The event flag number was invalid.
SS$_INSFARGS	A required argument was missing.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_NOSUCHBID	The calling process did not contain the branch identified by the BID passed in the bid argument.
SS$_NOSUCHTID	The calling process did not contain any branches in the transaction.
SS$_WRONGACMODE	The access mode of the caller was less privileged than that of a branch of the specified transaction in this process.

Removes a branch from a transaction and returns the outcome of the transaction. $END_BRANCHW always waits for the request to complete before returning to the caller. Other than this, it is identical to $END_BRANCH.

Format

SYS$END_BRANCHW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,bid

C Prototype

int sys$end_branchw (unsigned int efn, unsigned int flags, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int tid [4], unsigned int bid [4]);

Ends a transaction by attempting to commit it, and returns the outcome of the transaction.

Format

SYS$END_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]]

C Prototype

int sys$end_trans (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);

Arguments

efn

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

Number of the event flag that is set when the service completes. If this argument is omitted, event flag 0 is used.

flags

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

Flags specifying options for the service. The flags argument is a longword bit mask in which each bit corresponds to an option flag. The $DDTMDEF macro defines symbolic names for these option flags, which are defined in Table SYS-30.

All undefined bits must be 0. If this argument is omitted, no flag is set.

Table SYS-30 $END_TRANS Option Flags

Flag	Description
DDTM$M_SYNC	Set this flag to specify that successful synchronous completion is to be indicated by returning SS$_SYNCH. When SS$_SYNCH is returned, the asynchronous system trap (AST) routine is not called, the event flag is not set, and the I/O status block is not filled in.
DDTM$M_NOWAIT	Indicates that the service should return to the caller without waiting for final cleanup. Note that $END_TRANSW with the DDTM$M_NOWAIT flag set is not equivalent to $END_TRANS. The former does not return until the operation has been initiated, while $END_TRANS returns when the operation has been queued. The full range of status values may be returned from a nowait call.

iosb

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

I/O status block in which the following information is returned contains:

• The completion status of the service. This is returned as a condition value. See the Condition Values Returned section.
• The outcome of the transaction. If the service returns SS$_NORMAL, the outcome of the transaction is commit. If the service returns SS$_ABORT, the outcome of the transaction is abort.
• An abort reason code that gives one reason why the transaction aborted, if the completion status of the service is SS$_ABORT.

The $DDTMMSGDEF macro defines symbolic names for these abort reason codes, which are described in Table SYS-31:

Table SYS-31 Abort Reason Codes

Symbolic Name	Description
DDTM$_ABORTED	The application aborted the transaction.
DDTM$_COMM_FAIL	A communications link failed.
DDTM$_INTEGRITY	A resource manager integrity constraint check failed.
DDTM$_LOG_FAIL	A write operation to the transaction log failed.
DDTM$_ORPHAN_BRANCH	Unauthorized branch caused failure.
DDTM$_PART_SERIAL	A resource manager serialization check failed.
DDTM$_PART_TIMEOUT	The timeout specified by a resource manager expired.
DDTM$_SEG_FAIL	A process or image terminated.
DDTM$_SERIALIZATION	A DECdtm transaction manager serialization check failed.
DDTM$_SYNC_FAIL	The transaction was not globally synchronized (an authorized branch had not been added).
DDTM$_TIMEOUT	The timeout specified on $START_TRANS expired.
DDTM$_UNKNOWN	The reason is unknown.
DDTM$_VETOED	A resource manager was unable to commit the transaction.

The following diagram shows the structure of the I/O status block:

astadr

astprm

tid

If this argument is omitted, $END_TRANS ends the default transaction of the calling process.

Description

The End Transaction service ends a transaction by attempting to commit it, and returns the outcome of the transaction.

The $END_TRANS service:

• Initiates the commit protocol to determine whether the outcome of the transaction is commit or abort.

  Caution Do not call $END_TRANS while any transaction operation is in progress. If any of these operations is in progress when $END_TRANS is called, an unintended set of operations can be committed. This can invalidate application data managed by the resource managers participating in the transaction.

  
  Provided that no abort event has occurred, the DECdtm transaction manager delivers a prepare event to each Resource Manager (RM) participant in the transaction that:
  • Is associated with a Resource Manager instance (RMI) that requests prepare events.
  • Did not set the DDTM$M_COORDINATOR flag when it was added to the transaction.
  
  If there is only one such RM participant, the DECdtm transaction manager delivers a one-phase commit event, not prepare event, to that RM participant.
• $END_TRANS returns the outcome of the transaction. If it completes successfully, the outcome of the transaction is commit. If it returns the SS$_ABORT error, the outcome is abort.
• $END_TRANS removes from the specified transaction the branch that started the transaction.

Preconditions for the successful completion of $END_TRANS are:

• The calling process must contain the branch that started the transaction.
• The access mode of the caller must be the same as or more privileged than that of any branch of the specified transaction within this process. (See $START_TRANS and $START_BRANCH.)
• $START_BRANCH must have been performed for each authorized branch of the specified transaction.

$END_TRANS may fail for various reasons, including:

• The preconditions were not met.
• An abort event has occurred for the transaction.

Postconditions on successful completion of $END_TRANS are listed in Table SYS-32. $END_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) until after each authorized and synchronized branch of the transaction has initiated a call to $END_BRANCH.

$END_TRANS will not complete successfully (that is, the event flag will not be set, the AST routine will not be called, and the I/O status block will not be filled in) while the calling process is either:

• In an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction. RMS Journaling calls DECdtm in executive mode. Oracle Rdb and Oracle CODASYL DBMS call DECdtm in user mode.
• At AST level (in any access mode).

For example, if Oracle Rdb is a participant in the transaction, $END_TRANS will not complete successfully while the calling process is in supervisor, executive, or kernel mode, or while the calling process is at AST level. Successful completion of $END_TRANS is not indefinitely postponed by network failure.

Table SYS-32 Postconditions When$END_TRANS Completes Successfully

Postcondition	Meaning
The transaction is ended.	The meanings are: The TID of the transaction is invalid. Calls to any DECdtm system services except $GETDTI and $SETDTI that pass that TID will fail, and calls to resource managers that pass the TID will fail. The transaction no longer has any application or RM participants on the local node. All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final cleanup acknowledgments).
The outcome of the transaction is commit.	All the transaction operations by authorized branches that completed successfully before $END_TRANS was called will take effect. That is, the effects of these operations will be made permanent. Operations by unauthorized branches will be aborted. (An unauthorized branch is one without a matching $ADD_BRANCH.)
DECdtm quotas are returned.	All quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process.	If the transaction was the default transaction of the calling process, then it is now no longer the default.

Postconditions on completion with SS$_ABORT error are listed in Table SYS-33. $END_TRANS does not complete with the SS$_ABORT error until all branches on the local node have been removed from the transaction. Thus it does not complete with this error until after each authorized and synchronized branch on the local node has initiated a call to either $END_BRANCH or $ABORT_TRANS.

Note that the completion of $END_TRANS with the SS$_ABORT error is not indefinitely postponed by network failure.

Table SYS-33 Postconditions When$END_TRANS Completes with SS$_ABORT Error

Postcondition	Meaning
The transaction is ended.	If DDTM$M_NOWAIT is clear: The TID of the transaction is invalid. Calls to any DECdtm system services except $GETDTI and $SETDTI that pass the TID will fail, and calls to resource managers that pass the TID will fail. The transaction no longer has any application or RM participants on the local node. All communications about the transaction between the local DECdtm transaction manager and other DECdtm transaction managers are finished (including the final "cleanup" acknowledgments).
The outcome of the transaction is abort.	None of the operations of the transaction will ever take effect. The I/O status block contains one reason why the transaction was aborted. Note that if there are multiple reasons for the transaction aborting, the DECdtm transaction manager returns one of the reasons in the I/O status block. It may return different reasons to different branches in the transaction. For example, if the transaction timeout expires and a communications link fails, then either the DDTM$_TIMEOUT or DDTM$_COMM_FAIL abort reason code may be returned.
DECdtm quotas are returned.	If DDTM$M_NOWAIT is clear, all quotas allocated for the transaction by calls on the local node to DECdtm services are now returned.
The transaction is not the default transaction of the calling process.	If DDTM$M_NOWAIT is clear then, if the transaction was the default transaction of the calling process, then the transaction is now no longer the default.

There is also a wait form of the service, $END_TRANSW.

Required Access or Privileges

None

Required Quotas

ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL	If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.
SS$_SYNCH	The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ABORT	The transaction aborted. See the abort reason code returned in the I/O status block for one reason why the transaction aborted.
SS$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	The options flags were invalid.
SS$_CURTIDCHANGE	The tid argument was omitted and a call to change the default transaction of the calling process was in progress.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_ILLEFC	The event flag number was invalid.
SS$_INSFARGS	A required argument was missing.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_NOCURTID	An attempt was made to end the default transaction (the tid argument was omitted), but the calling process did not have a default transaction.
SS$_NOSUCHTID	The calling process did not contain any branches in the transaction.
SS$_NOTORIGIN	The calling process did not start the transaction.
SS$_WRONGACMODE	The access mode of the caller was less privileged than that of a branch of the transaction in this process.
SS$_WRONGSTATE	The calling process had already called either $ABORT_TRANS with a zero BID or $END_TRANS to end the transaction, and processing had not completed.

Ends a transaction by attempting to commit it, and returns the outcome of the transaction.

$END_TRANSW always waits for the request to complete before returning to the caller. Other than this, it is identical to $END_TRANS.

Do not call $END_TRANSW from asynchronous system trap (AST) level, or from an access mode that is more privileged than the DECdtm calls made by any resource manager participant in the transaction. If you do, the $END_TRANSW service will wait indefinitely.

Format

SYS$END_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid]]

C Prototype

int sys$end_transw (unsigned int efn, unsigned int flags, struct _iosb *iosb,...);

Queues a new lock or lock conversion on a resource.

The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get Lock Information) 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.

On Alpha systems, this service accepts 64-bit addresses.

For additional information about system service completion, see the Synchronize ($SYNCH) service.

Format

SYS$ENQ [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid] ,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id] ,[nullarg]

C Prototype

int sys$enq (unsigned int efn, unsigned int lkmode, struct _lksb *lksb, unsigned int flags, void *resnam, unsigned int parid, void (*astadr)(__unknown_params), unsigned int acmode, unsigned int rsdm_id,...);

Arguments

efn

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

Number of the event flag to be set when the request has been granted or canceled. Cancellation occurs if you use $DEQ with the cancel modifier or if the waiting request is chosen to break a deadlock. The efn argument is a longword containing this number; however, $ENQ uses only the low-order byte.

Upon request initiation, $ENQ clears the specified event flag (or event flag 0 if efn was not specified). Then, when the lock request is granted, the specified event flag (or event flag 0) is set unless you specified the LCK$M_SYNCSTS flag in the flags argument.

lkmode

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

Lock mode requested. The lkmode argument is a longword specifying this lock mode.

Each lock mode has a symbolic name. The $LCKDEF macro defines these symbolic names. The following table gives the symbolic name and description for each lock mode:

Lock Mode	Description
LCK$K_NLMODE	Null mode. This mode grants no access to the resource but serves as a placeholder and indicator of future interest in the resource. The null mode does not inhibit locking at other lock modes; further, it prevents the deletion of the resource and lock value block, which would otherwise occur if the locks held at the other lock modes were dequeued.
LCK$K_CRMODE	Concurrent read. This mode grants the caller read access to the resource while permitting write access to the resource by other users. This mode is used to read data from a resource in an unprotected manner, because other users can modify that data as it is being read. This mode is typically used when additional locking is being performed at a finer granularity with sublocks.
LCK$K_CWMODE	Concurrent write. This mode grants the caller write access to the resource while permitting write access to the resource by other users. This mode is used to write data to a resource in an unprotected fashion, because other users can simultaneously write data to the resource. This mode is typically used when additional locking is being performed at a finer granularity with sublocks.
LCK$K_PRMODE	Protected read. This mode grants the caller read access to the resource while permitting only read access to the resource by other users. Write access is not allowed. This is the traditional share lock.
LCK$K_PWMODE	Protected write. This mode grants the caller write access to the resource while permitting only read access to the resource by other users; the other users must have specified concurrent read mode access. No other writers are allowed access to the resource. This is the traditional update lock.
LCK$K_EXMODE	Exclusive. The exclusive mode grants the caller write access to the resource and allows no access to the resource by other users. This is the traditional exclusive lock.

The following table shows the compatibility of lock modes:

Table SYS-34 Compatibility of Lock Modes

Mode of	Mode of Currently Granted Locks
Requested Lock	NL	CR	CW	PR	PW	EX
NL	Yes	Yes	Yes	Yes	Yes	Yes
CR	Yes	Yes	Yes	Yes	Yes	No
CW	Yes	Yes	Yes	No	No	No
PR	Yes	Yes	No	Yes	No	No
PW	Yes	Yes	No	No	No	No
EX	Yes	No	No	No	No	No

NL---Null
CR---Concurrent read
CW---Concurrent write
PR---Protected read
PW---Protected write
EX---Exclusive

lksb

The lock status block can optionally contain a 16-byte lock value block. The initial value of the lock value block is zero (0). When you specify the LCK$M_VALBLK flag in the flags argument, the lock status block contains a lock value block. In this case, the 16-byte lock value block appears at the beginning of the first byte following the eighth byte of the lock status block, bringing the total length of the lock status block to 24 bytes.

The following diagram shows the format of the lock status block and the optional lock value block:

The following table defines the status block fields:

Callers of $ENQ are provided with copies of the updated lock value block from the lock database in the following way: when $ENQ grants a new lock to the caller or converts the caller's existing lock to the same lock mode or a higher lock mode, $ENQ copies the lock value block from the lock database to the caller's lock value block, provided the caller has specified the LCK$M_VALBLK flag.

The Description section describes events that can cause the lock value block to become invalid.

flags

The $LCKDEF macro defines a symbolic name for each flag bit. The following table describes each flag:

NL---Null lock
CR---Concurrent read
CW---Concurrent write
PR---Protected read
PW---Protected write
EX---Exclusive lock

resnam

If you are creating a new lock, the resnam argument should be specified because the default value for the resnam argument produces an error when it is used to create a lock. The resnam argument is ignored for lock conversions.

parid

If you do not specify this argument or specify it as 0, $ENQ assumes that the lock does not have a parent lock. This argument is optional for new locks and is ignored for lock conversions.

astadr

If you specify the astadr argument, the AST routine executes at the same access mode as the caller of $ENQ.

astprm

blkast

You can pass a parameter to this routine by using the astprm argument.

acmode

This argument does not affect the access mode associated with the lock or its blocking and completion ASTs. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the following symbols for the four access modes:

The $ENQ service associates an access mode with the lock in the following way:

• If you specified a parent lock (with the parid argument), $ENQ uses the access mode associated with the parent lock and ignores both the acmode argument and the caller's access mode.
• If the lock has no parent lock (you did not specify the parid argument or specified it as 0), $ENQ uses the least privileged of the caller's access mode and the access mode specified by the acmode argument. If you do not specify the acmode argument, $ENQ uses the caller's access mode.

rsdm_id

nullarg

Description

The Enqueue Lock Request service queues a new lock or lock conversion on a resource. The $ENQ service completes asynchronously; that is, it returns to the caller after queuing the lock request without waiting for the lock to be either granted or converted. For synchronous completion, use the Enqueue Lock Request and Wait ($ENQW) service. The $ENQW service is identical to the $ENQ service in every way except that $ENQW returns to the caller when the lock is either granted or converted.

The $ENQ service uses system dynamic memory for the creation of the lock and resource blocks.

When $ENQ queues a lock request, it returns the status of the request in R0 and writes the lock identification of the lock in the lock status block. Then, when the lock request is granted, $ENQ writes the final completion status in the lock status block, sets the event flag, and calls the AST routine if this has been requested.

When $ENQW queues a lock request, it returns status in R0 and in the lock status block when the lock has been either granted or converted. Where applicable, it simultaneously sets the event flag and calls the AST routine.

Invalidation of the Lock Value Block

In some situations, the lock value block can become invalid. In these situations, $ENQ warns the caller by returning the condition value SS$_VALNOTVALID in the lock status block, provided the caller has specified the flag LCK$M_VALBLK in the flags argument.

The SS$_VALNOTVALID condition value is a warning message, not an error message; therefore, the $ENQ service grants the requested lock and returns this warning on all subsequent calls to $ENQ until either a new lock value block is written to the lock database or the resource is deleted. Resource deletion occurs when no locks are associated with the resource.

The following events can cause the lock value block to become invalid:

• If any process holding a protected write or exclusive mode lock on a resource is terminated abnormally, the lock value block becomes invalid.
• If a process holding a protected write or exclusive mode lock on the resource calls the Dequeue Lock Request ($DEQ) service to dequeue this lock and specifies the flag LCK$M_INVVALBLK in the flags argument, the lock value block maintained in the lock database is marked invalid.
• If a node in an OpenVMS Cluster system fails, and a process on that node was holding or might have been holding a protected write or exclusive mode lock on the resource, the lock value block becomes invalid.
  This situation is dependant on which cluster node is the master node for the resource. The following describes the two ways in which this situation can arise:
  1. If a node was holding a protected write or exclusive mode lock on the resource:
     If the node that failed was not the master of the resource tree, the master node will know what locks were held by the node that failed. These locks will be removed from the resource and if a removed lock was for protected write or exclusive mode, the lock value block becomes in valid.
  2. If a node might have been holding a protected write or exclusive mode lock on the resource:
     If the node that failed was the master of the resource, a remaining node in the cluster will become the new master. If the new master finds that all granted locks on the resource were for null mode locks, then the new master does not know if the failed node held a protected write or exclusive mode lock. The lock value block will be set to invalid for this case.
     If the resource has any granted lock with a mode greater than null mode, then the failed node could not have held a protected write or exclusive mode lock and the lock value block will not be marked as invalid.

Required Access or Privileges

To queue a lock on a systemwide resource, the calling process must either have SYSLCK privilege or be executing in executive or kernel mode.

To specify a parent lock when queuing a lock, the access mode of the caller must be equal to, or less privileged than, the access mode associated with the parent lock.

To queue a lock conversion, the access mode associated with the lock being converted must be equal to, or less privileged than, the access mode of the calling process.

Required Quota

• Enqueue limit (ENQLM) quota
• AST limit (ASTLM) quota in lock conversion requests that you specify either the astadr or blkast argument

Related Services

$DEQ, $ENQW, $GETLKI, $GETLKIW, $SET_RESOURCE_DOMAIN

Condition Values Returned

SS$_NORMAL	The service completed successfully; the lock request was successfully queued.
SS$_SYNCH	The service completed successfully; the LCK$M_SYNCSTS flag in the flags argument was specified, and $ENQ was able to grant the lock request immediately.
SS$_ACCVIO	The lock status block or the resource name cannot be read.
SS$_BADPARAM	You specified an invalid lock mode in the lkmode argument.
SS$_CVTUNGRANT	You attempted a lock conversion on a lock that is not currently granted.
SS$_EXDEPTH	The limit of levels of sublocks has been exceeded.
SS$_EXENQLM	The process has exceeded its enqueue limit (ENQLM) quota.
SS$_INSFMEM	The system dynamic memory is insufficient for creating the necessary data structures.
SS$_IVBUFLEN	The length of the resource name was either 0 or greater than 31.
SS$_IVLOCKID	You specified an invalid or nonexistent lock identification, or the lock identified by the lock identification has an associated access mode that is more privileged than the caller's, or the access mode of the parent was less privileged than that of the caller.
SS$_NOLOCKID	No lock identification was available for the lock request.
SS$_NOSYSLCK	The LCK$M_SYSTEM flag in the flags argument was specified, but the caller lacks the necessary SYSLCK privilege.
SS$_NOTQUEUED	The lock request was not queued; the LCK$M_NOQUEUE flag in the flags argument was specified, and $ENQ was not able to grant the lock request immediately.
SS$_PARNOTGRANT	The parent lock specified in the parid argument was not granted.

Condition Values Returned in the Lock Status Block

SS$_NORMAL	The service completed successfully; the lock was successfully granted or converted.
SS$_ABORT	The lock was dequeued (by the $DEQ service) before $ENQ could grant the lock.
SS$_CANCEL	The lock conversion request has been canceled and the lock has been regranted at its previous lock mode. This condition value is returned when $ENQ queues a lock conversion request, the request has not been granted yet (it is in the conversion queue), and, in the interim, the $DEQ service is called (with the LCK$M_CANCEL flag specified) to cancel this lock conversion request. If the lock is granted before $DEQ can cancel the conversion request, the call to $DEQ returns the condition value SS$_CANCELGRANT, and the call to $ENQ returns SS$_NORMAL.
SS$_DEADLOCK	A deadlock was detected.
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$_NODOMAIN	The RSDM_ID argument passed to the $ENQ call either does not correspond to a valid resource domain for your process, or the system is not running the audit server process.
SS$_VALNOTVALID	The lock value block is marked invalid. This warning message is returned only if the caller has specified the flag LCK$M_VALBLK in the flags argument. Note that the lock has been successfully granted despite the return of this warning message. Refer to the Description section for a complete discussion of lock value block invalidation.

Queues a lock on a resource. The $ENQW service completes synchronously; that is, it returns to the caller when the lock has been either granted or converted. For asynchronous completion, use the Enqueue Lock Request ($ENQ) service; $ENQ returns to the caller after queuing the lock request, without waiting for the lock to be either granted or converted. In all other respects, $ENQW is identical to $ENQ. See the $ENQ description for all other information about the $ENQW service.

For additional information about system service completion, see the Synchronize ($SYNCH) service documentation.

The $ENQ, $ENQW, $DEQ, and $GETLKI services together provide the user interface to the Lock Management facility.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ENQW [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid] ,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]

C Prototype

int sys$enqw (unsigned int efn, unsigned int lkmode, struct _lksb *lksb, unsigned int flags, void *resnam, unsigned int parid, void (*astadr)(__unknown_params), unsigned __int64 astprm, void (*blkast)(__unknown_params), unsigned int acmode, unsigned int rsdm_id,...);

The Enter service inserts a file name in a directory.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Generates a security erase pattern.

Format

SYS$ERAPAT [type] ,[count] ,[patadr]

C Prototype

int sys$erapat (int type, unsigned int count, unsigned int *patadr);

Arguments

type

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

Type of storage to be written over with the erase pattern. The type argument is a longword containing the type of storage.

The three storage types, together with their symbolic names, are defined by the $ERADEF macro and are listed in the following table:

Storage Type	Symbolic Name
Main memory	ERA$K_MEMORY
Disk	ERA$K_DISK
Tape	ERA$K_TAPE

count

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

Number of times that $ERAPAT has been called in a single security erase operation. The count argument is a longword containing the iteration count.

You should call the $ERAPAT service initially with the count argument set to 1, the second time with the count argument set to 2, and so on, until the status code SS$_NOTRAN is returned.

patadr

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Security erase pattern to be written. The patadr argument is the address of a longword into which the security erase pattern is to be written.

Description

The Get Security Erase Pattern service generates a security erase pattern that can be written into memory areas containing outdated but sensitive data to make it unreadable. This service is used primarily by the operating system, but it can also be used by users who want to perform security erase operations on foreign disks.

You should call the $ERAPAT service iteratively until the completion status SS$_NOTRAN is returned.

The following example demonstrates how to use the $ERAPAT service to perform a security erase to a disk. Note that, after each call to $ERAPAT, a test for the status SS$_NOTRAN is made. If SS$_NOTRAN has not been returned, $QIO is called to write the pattern returned by $ERAPAT onto the disk. After this write, $ERAPAT is called again and the cycle is repeated until the code SS$_NOTRAN is returned, at which point the security erase procedure is complete.

; Code fragment that erases 20 blocks (blocks 15 through 34) on a disk ; PATTERN: .LONG 0 ; Cell to contain output from $ERAPAT CHANNEL: .WORD 0 ; Channel assigned to disk device DEVICE: .ASCID /DISK:/ ; Disk device name . . . $ASSIGN_S DEVNAM=DISK,- ; Assign a channel to the device CHAN=CHANNEL BLBC RO, EXIT ; Branch if error . . . MOVL #1, R2 ; Set initial count $ERADEF ; Macro to define names ; used by $ERAPAT 10$: $ERAPAT_S - ; Call the $ERAPAT service COUNT=R2,- TYPE=#ERA$K_DISK,- PATADR=PATTERN BLBC R0, EXIT ; Branch if error CMPL #SS$_NOTRAN, R0 ; Are we done? BEQL EXIT ; Branch if so $QIO_S CHAN=CHANNEL,- FUNC=#I0$_WRITELBLK!IO$M_ERASE,- ; Call P1=PATTERN,- ; to the $QIO service P2=#<20*512>,- ; to write the erase P3=#15 ; pattern INCL R2 ; Increase count BRB 10$ EXIT: . . .

Required Access or Privileges

None.

Required Quota

None.

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully; proceed with the next erase step.
SS$_NOTRAN	The service completed successfully; security erase completed.
SS$_ACCVIO	The patadr argument cannot be written by the caller.
SS$_BADPARAM	The type argument or count argument is invalid.

The Erase service deletes a disk file and removes the file's directory entry specified in the path to the file. If additional directory entries have been created for this file by the Enter service, you must use the Remove service to delete them.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Initiates image rundown when the current image in a process completes execution. Control normally returns to the command interpreter.

Format

SYS$EXIT [code]

C Prototype

int sys$exit (unsigned int code);

Argument

code

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

Longword value to be saved in the process header as the completion status of the current image. If you do not specify this argument in a macro call, a value of 1 is passed as the completion code for VAX MACRO and VAX BLISS--32, and a value of 0 is passed for other languages. You can test this value at the command level to provide conditional command execution.

Description

The $EXIT service is unlike all other system services in that it does not return status codes in R0 or anywhere else. The $EXIT service does not return control to the caller; it performs an exit to the command interpreter or causes the process to terminate if no command interpreter is present.

Required Access or Privileges

None

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Adds a specified number of new virtual pages to a process's program region or control region for the execution of the current image. Expansion occurs at the current end of that region's virtual address space.

Format

SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]

C Prototype

int sys$expreg (unsigned int pagcnt, struct _va_range *retadr, unsigned int acmode, char region);

Arguments

pagcnt

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

Number of pages (on VAX systems) or pagelets (on Alpha systems) to add to the current end of the program or control region. The pagcnt argument is a longword value containing this number.

On Alpha systems, the specified value is rounded up to an even multiple of the CPU-specific page size.

retadr

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Starting and ending process virtual addresses of the pages that $EXPREG has actually added. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.

acmode

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

Access mode to be associated with the newly added pages. The acmode argument is a longword containing the access mode.

The most privileged access mode used is the access mode of the caller.

The newly added pages are given the following protection: (1) read and write access for access modes equal to or more privileged than the access mode used in the call, and (2) no access for access modes less privileged than that used in the call.

region

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

Number specifying which program region is to be expanded. The region argument is a longword value. A value of 0 (the default) specifies that the program region (P0 region) is to be expanded. A value of 1 specifies that the control region (P1 region) is to be expanded.

Description

The Expand Program/Control Region service adds a specified number of new virtual pages to a process's program region or control region for the execution of the current image. Expansion occurs at the current end of that region's virtual address space.

The new pages, which were previously inaccessible to the process, are created as demand-zero pages.

Because the bottom of the user stack is normally located at the end of the control region, expanding the control region is equivalent to expanding the user stack. The effect is to increase the available stack space by the specified amount.

The starting address returned is always the first available page in the designated region; therefore, the ending address is smaller than the starting address when the control region is expanded and is larger than the starting address when the program region is expanded.

If an error occurs while pages are being added, the retadr argument (if specified) indicates the pages that were successfully added before the error occurred. If no pages were added, both longwords of the retadr argument contain the value --1.

Required Access or Privileges

None

Required Quota

The process's paging file quota (PGFLQUOTA) must be sufficient to accommodate the increased size of the virtual address space.

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW

Typically, the information returned in the location addressed by the retadr argument (if specified) can be used as the input range to the Delete Virtual Address Space ($DELTVA) service.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The return address array cannot be written by the caller.
SS$_EXQUOTA	The process exceeded its paging file quota.
SS$_ILLPAGCNT	The specified page count was less than 1 or would cause the program or control region to exceed its maximum size.
SS$_INSFWSL	The process's working set limit is not large enough to accommodate the increased virtual address space.
SS$_VASFULL	The process's virtual address space is full. No space is available in the process page table for the requested regions.

On Alpha systems, adds a specified number of demand-zero allocation pages to a process's virtual address space for the execution of the current image. Expansion occurs at the next free available address within the specified region.

This service accepts 64-bit addresses.

Format

SYS$EXPREG_64 region_id_64 ,length_64 ,acmode ,flags ,return_va_64 ,return_length_64

C Prototype

int sys$expreg_64 (struct _generic_64 *region_id_64, unsigned __int64 length_64, unsigned int acmode, unsigned int flags, void *(*(return_va_64)), unsigned __int64 *return_length_64);

Arguments

region_id_64

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The region ID associated with the virtual address range to be expanded. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each of the three default regions in P0, P1, and P2 space.

The following region IDs are defined:

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can be specified.

length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

Length of the virtual address space to be created. The length specified must be a multiple of CPU-specific pages.

acmode

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

Access mode associated with the call to $EXPREG_64. The access mode determines the owner mode of the pages as well as the read and write protection on the pages. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes.

The $EXPREG_64 service uses whichever of the following two access modes is least privileged:

• The access mode specified by the acmode argument.
• The access mode of the caller. The protection of the pages is read/write for the resultant access mode and those more privileged.

Address space cannot be created within a region that has a create mode associated with it that is more privileged than the caller's mode. The condition value SS$_IVACMODE is returned if the caller is less privileged than the create mode for the region.

flags

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

Flag mask controlling the characteristics of the demand-zero pages created. The flags argument is a longword bit vector in which each bit corresponds to a flag. The $VADEF macro and the VADEF.H file define a symbolic name for each flag. You construct the flags argument by performing a logical OR operation on the symbol names for all desired flags.

All bits in the flags argument are reserved for future use by HP and should be specified as 0. The condition value SS$_IVVAFLG is returned if any bits are set.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of a created virtual address range. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length in bytes of the virtual address range created.

Description

The Expand Virtual Address Space service is a kernel mode service that can be called from any mode. This service adds a range of demand-zero allocation pages to a process's virtual address space for the execution of the current image. Expansion occurs at the next free available address within the specified region. The new pages, which were previously inaccessible to the process, are created as demand-zero pages.

The returned address is always the lowest virtual address in the range of pages created. The returned length is always an unsigned byte count indicating the length of the range of pages created.

Successful return status from $EXPREG_64 Expand Virtual Address service means that the specified region's virtual address space was expanded by the number of bytes specified in the length_64 argument.

If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64 and return_length_64 arguments. If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully added before the error occurred. If no pages were added, the return_va_64 argument will contain the value --1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

None

Required Quota

The working set quota (WSQUOTA) of the process must be sufficient to accommodate the increased length of the process page table required by the increase in virtual address space.

The process's paging file quota (PGFLQUOTA) must be sufficient to accommodate the increased size of the virtual address space.

Related Services

$CREATE_BUFOBJ_64, $CREATE_REGION_64, $CRETVA_64, $DELETE_REGION_64, $DELTVA_64, $LCKPAG_64, $LKWSET_64, $PURGE_WS, $SETPRT_64, $ULKPAG_64, $ULWSET_64

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The return_va_64 argument or the return_length_64 argument cannot be written by the caller.
SS$_EXPGFLQUOTA	The process exceeded its paging file quota.
SS$_INSFWSL	The process's working set limit is not large enough to accommodate the increased virtual address space.
SS$_IVACMODE	The caller's mode is less privileged than the create mode associated with the region.
SS$_IVREGID	An invalid region ID was specified.
SS$_IVVAFLG	An invalid flag, a reserved flag, or an invalid combination of flags and arguments was specified.
SS$_LEN_NOTPAGMULT	The length_64 argument is not a multiple of CPU-specific pages.
SS$_NOSHPTS	The region ID of a shared page table region was specified.
SS$_REGISFULL	The specified virtual region is full.

The Extend service increases the amount of space allocated to a disk file. This service is most useful for extending relative files and indexed files when you are doing block I/O transfers using the Write service.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Converts a binary value into an ASCII character string in decimal, hexadecimal, or octal notation; returns the character string in an output string; and inserts variable character-string data into an output string.

The Formatted ASCII Output with List Parameter ($FAOL) service provides an alternate method for specifying input parameters when calling the $FAO system service.

The formats for both services are shown in the Format section.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$FAO ctrstr ,[outlen] ,outbuf ,[p1]...[pn]

SYS$FAOL ctrstr ,[outlen] ,outbuf ,[prmlst]

C Prototype

int sys$fao (void *ctrstr, unsigned short int *outlen, void *outbuf,...);

int sys$faol (void *ctrstr, unsigned short int *outlen, void *outbuf, void *prmlst);

Arguments

ctrstr

OpenVMS usage:	char_string
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)

Control string passed to $FAO that contains the text to be output together with one or more $FAO directives. $FAO directives are used to specify repeat counts or the output field length, or both, and they are preceded by an exclamation point (!). The ctrstr 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 control string. The formatting of the $FAO directives is described in the Description section.

There is no restriction on the length of the control string or on the number of $FAO directives it can contain; however, if an exclamation point must appear in the output string, it must be represented in the control string by a double exclamation point (!!). A single exclamation point in the control string indicates to $FAO that the next characters are to be interpreted as FAO directives.

When $FAO processes the control string, it writes to the output buffer each character that is not part of an $FAO directive.

If the $FAO directive is valid, $FAO processes it. If the directive requires a parameter, $FAO processes the next consecutive parameter in the specified parameter list. If the $FAO directive is not valid, $FAO terminates and returns a condition value in R0.

Table SYS-36 lists and describes the $FAO directives. Table SYS-37 shows the $FAO output field lengths and their fill characters.

The $FAO service reads parameters from the argument list specified in the call; these arguments have the names p1, p2, p3, and so on, up to p17. Each argument specifies one parameter. Because $FAO accepts a maximum of 17 parameters in a single call, you must use $FAOL if the number of parameters exceeds 17. The $FAOL service accepts any number of parameters used with the prmlst argument.

outlen

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 in bytes of the fully formatted output string returned by $FAO. The outlen argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a word containing this value.

outbuf

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)

Output buffer into which $FAO writes the fully formatted output string. The outbuf 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 output buffer. The maximum number of bytes written is limited to 64K.

p1 to pn

OpenVMS usage:	varying_arg
type:	quadword (signed)
access:	read only
mechanism:	by value

$FAO directive parameters. The p1 argument is a quadword containing the parameter needed by the first $FAO directive encountered in the control string, the p2 argument is a quadword containing the parameter needed for the second $FAO directive, and so on for the remaining arguments up to p17. If an $FAO directive does not require a parameter, that $FAO directive is processed without reading a parameter from the argument list.

Depending on the directive, a parameter can be a value to be converted, a 32- or 64-bit address of a string to be inserted into the output string, or a length or argument count. Each directive in the control string might require a corresponding parameter or parameters.

prmlst

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

List of $FAO directive parameters to be passed to $FAOL. The prmlst argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a list of longwords wherein each longword is a parameter. The $FAOL service processes these parameters sequentially as it encounters, in the control string, $FAO directives that require parameters.

The parameter list can be a data structure that already exists in a program and from which certain values are to be extracted.

Description

The Formatted ASCII Output ($FAO) service converts a binary value into an ASCII character string in decimal, hexadecimal, or octal notation and returns the character string in an output string, and inserts variable character string data into an output string.

The Formatted ASCII Output with List Parameter ($FAOL) service provides an alternate way to specify input parameters for a call to the $FAO system service. The formats for both $FAO and $FAOL are shown in the Format section.

The $FAO_S macro form uses a PUSHL instruction for all parameters (p1 through p17) passed to the service; if you specify a symbolic address, it must be preceded with a number sign (#) or loaded into a register.

You can specify a maximum of 17 parameters on the $FAO macro. If more than 17 parameters are required, use the $FAOL macro.

This service does not check the length of the argument list and therefore cannot return the SS$_INSFARG (insufficient arguments) error status code. If the service does not receive a sufficient number of arguments (for example, if you omit required commas in the call), you might not get the desired result.

$FAO Directives

$FAO directives can appear anywhere in the control string. The general format of an $FAO directive is as follows:

!DD

The exclamation point (!) specifies that the following characters are to be interpreted as an $FAO directive, and the characters DD represent a 1- or 2-character $FAO directive.

Note When the characters of the $FAO directive are alphabetic, they must be uppercase.

An $FAO directive can optionally specify the following:

• A repeat count. The format is as follows:

  !n(DD)

  
  In this case n is a decimal value specifying the number of times that $FAO is to repeat the directive. If the directive requires a parameter or parameters, $FAO uses successive parameters from the parameter list for each repetition of the directive; it does not use the same parameters for each repetition. The parentheses are required syntax.

• An output field length. The format is as follows:

  !mDD

  
  In this case m is a decimal value specifying the length of the field (within the output string) into which $FAO is to write the output resulting from the directive. The length is expressed as a number of characters.

• Both a repeat count and output field length. In this case the format is as follows:

  !n(mDD)

You can specify repeat counts and output field lengths as variables by using a number sign (#) in place of an absolute numeric value:

• If you specify a number sign for a repeat count, the next parameter passed to $FAO must contain the count.
• If you specify a number sign for an output field length, the next parameter must contain the length value.
• If you specify a number sign for both the output field length and for the repeat count, only one length parameter is required; each output string will have the specified length.
• If you specify a number sign for the repeat count, the output field length, or both, the parameters specifying the count, length, or both must precede other parameters required by the directive.

Numeric FAO output directives (B, W, L, Q, I, A, H, J) can include the indirect directive @. This immediately precedes the directive (@DD), and indicates that the next parameter is the address of the value instead of the value itself. This directive must be used with any directive that can produce a quadword output when using $FAOL; otherwise, $FAOL creates a 64-bit sign-extended value. This includes the Q, A, I, H, and J directives.

• The indirect directive can be used with repeat counts and output field lengths. In this case the format is as follows:

  !n(m@DD)

To ensure that addresses and integers are displayed properly on the system, use the following conventions when using the $FAO and $FAOL system services:

• Identify longword data as !xL (where x is O, X, Z, U, or S).
• On Alpha systems, identify quadword data as !xQ for $FAO and $FAOL_64 or !@xQ for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
• If the size of an address is determined by operating system software (32 bits on VAX and 64-bits on Alpha systems), identify the address as !xA for $FAO and $FAOL_64 or !@xA for $FAOL (where x is O, X, Z, U, or S).
• If the size of an address is determined by the hardware architecture (32 bits on VAX, but 64 bits on Alpha, identify the address as !xH for $FAO and $FAOL_64 or !@xH for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
• If the size of an integer is determined by operating system software (32 bits on both VAX and Alpha systems), identify the integer as !xI for $FAO and $FAOL_64 or !@xI for $FAOL (where x is O, X, Z, U, or S).
• If the size of an integer is determined by the hardware architecture (32 bits on VAX, but 64 bits on Alpha), identify the address as !xJ for $FAO and $FAOL_64 or !@xJ for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.

Table SYS-36 lists $FAO directives.

Table SYS-36 $FAO Directives

Directive	Description
Directives for Character String Substitution
!AC	Inserts a counted ASCII string. It requires one parameter: the address of the string to be inserted. The first byte of the string must contain the length (in characters) of the string.
!AD	Inserts an ASCII string. It requires two parameters: the length of the string and the address of the string. Each of these parameters is a separate argument.
!AF	Inserts an ASCII string and replaces all nonprintable ASCII codes with periods (.). It requires two parameters: the length of the string and the address of the string. Each of these parameters is a separate argument.
!AS	Inserts an ASCID string. It requires one parameter: the address of a character string descriptor pointing to the string. $FAO assumes that the descriptor is a CLASS_S (static) or CLASS_D (dynamic) string descriptor. Other descriptor types might give incorrect results.
!AZ	Inserts a zero-terminated (ASCIZ) string. It requires one parameter: the address of a zero-terminated string.
Directives for Zero-Filled Numeric Conversion
!OB	Converts a byte value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!OW	Converts a word value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!OL	Converts a longword value to the ASCII representation of the value's octal equivalent. It requires one parameter: the value to be converted.
!OQ	Converts on Alpha systems a quadword to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!OA	Converts an address to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!OI	Converts an integer to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!OH	Converts an address to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!OJ	Converts an integer to the ASCII representation of its octal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!XB	Converts a byte value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!XW	Converts a word value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!XL	Converts a longword value to the ASCII representation of the value's hexadecimal equivalent. It requires one parameter: the value to be converted.
!XQ	Converts on Alpha systems a quadword to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the value to be converted. This directive cannot be used from DCL.
!XA	Converts an address to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!XI	Converts an integer to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!XH	Converts an address to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!XJ	Converts an integer to the ASCII representation of its hexadecimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit sign-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!ZB	Converts an unsigned byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!ZW	Converts an unsigned word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!ZL	Converts an unsigned longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.
!ZQ	Converts on Alpha systems an unsigned quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the value to be converted. This directive cannot be used from DCL.
!ZA	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!ZI	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!ZH	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!ZJ	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit zero-extended value is written to the output buffer. It receives one parameter: the value to be converted. 2
Directives for Blank-Filled Numeric Conversion
!UB	Converts an unsigned byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!UW	Converts an unsigned word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!UL	Converts an unsigned longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.
!UQ	Converts on Alpha systems an unsigned quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!UA	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!UI	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!UH	Converts an unsigned address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!UJ	Converts an unsigned integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 64-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!SB	Converts a signed byte value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order byte of the longword parameter.
!SW	Converts a signed word value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted. $FAO uses only the low-order word of the longword parameter.
!SL	Converts a signed longword value to the ASCII representation of the value's decimal equivalent. It requires one parameter: the value to be converted.
!SQ	Converts on Alpha systems a signed quadword to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. This directive cannot be used from DCL.
!SA	Converts a signed address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!SI	Converts a signed integer to the ASCII representation of its equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 1
!SH	Converts a signed address to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
!SJ	Converts a signed integer to the ASCII representation of its decimal equivalent. Must use the indirect directive @ to output the quadword value for $FAOL; otherwise, a 32-bit value is written to the output buffer. It receives one parameter: the address of the value to be converted. 2
Directives for Output String Formatting
!/	Inserts a new line, that is, a carriage return and line feed. It takes no parameters.
!_	Inserts a tab. It takes no parameters.
!^	Inserts a form feed. It takes no parameters.
!!	Inserts an exclamation point. It takes no parameters.
!%S	Inserts the letter S if the most recently converted numeric value is not 1. An uppercase S is inserted if the character before the !%S directive is an uppercase character; a lowercase s is inserted if the character is lowercase.
!%T	Inserts the system time. It takes one parameter: the address of a quadword time value to be converted to ASCII. If you specify 0, the current system time is inserted.
!%U	Converts a longword integer UIC to a standard UIC specification in the format [xxx,yyy], where xxx is the group number and yyy is the member number. It takes one parameter: a longword integer. The directive inserts the surrounding brackets ([ ]) and comma (,).
!%I	Converts a longword to the appropriate alphanumeric identifier. If the longword represents a UIC, surrounding brackets ([ ]) and comma (,) are added as necessary. If no identifier exists and the longword represents a UIC, the longword is formatted as in !%U. Otherwise it is formatted as in !XL with a preceding !%X added to the formatted result.
!%D	Inserts the system date and time. It takes one parameter: the address of a quadword time value to be converted to ASCII. If you specify 0, the current system date and time is inserted.
!n%C	Inserts a character string when the most recently evaluated argument has the value n. (Recommended for use with multilingual products.)
!%E	Inserts a character string when the value of the most recently evaluated argument does not match any preceding !n%C directives. (Recommended for use with multilingual products.)
!%F	Makes the end of a plurals statement.
!n<	See description of next directive (!>).
!>	This directive and the preceding one (!n<) are used together to define an output field width of n characters within which all data and directives to the right of !n< and to the left of !> are left-justified and blank-filled. It takes no parameters.
!n*c	Repeats the character c in the output string n times.
Directives for Parameter Interpretation
!--	Causes $FAO to reuse the most recently used parameter in the list. It takes no parameters.
!+	Causes $FAO to skip the next parameter in the list. It takes no parameters.

Table SYS-37 shows the $FAO output field lengths and their fill characters.

Required Access or Privileges

None

Required Quota

None

Related Services

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

Condition Values Returned

SS$_BUFFEROVF	The service completed successfully. The formatted output string overflowed the output buffer and has been truncated.
SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The ctrstr, p1 through pn, or prmlst arguments cannot be read, or the outlen argument cannot be written (it can specify 0).
SS$_BADPARAM	You specified an invalid directive in the $FAO control string.
SS$_OVERMAXARG	Maximum parameter count exceeded.

$FAO Control String Examples

Each of the following examples shows an $FAO control string with several directives, parameters defined as input for the directives, and the calls to $FAO to format the output strings.

Each example is accompanied by notes. These notes show the output string created by the call to $FAO and describe in more detail some considerations for using directives. The sample output strings show the underscore character (_) for each space in all places where $FAO output contains multiple spaces.

Each of the first 10 examples (numbered 1 through 10) refers to the following output fields but does not include these fields within the examples.

int status, /* Status of system calls */ outlen; /* Length of output string from $FAO */ char out_buffer[80]; /* Buffer for $FAO output */ $DESCRIPTOR(out_desc, out_buffer); /* Descriptor for out_buffer */

Each of the 10 examples also assumes the caller of each example will check the returned status, and write the output string produced by $FAO if no error occurred. The following code fragment shows how the example call may be made, and the resultant string output to the user's terminal.

#include <stdio.h> #include <stsdef.h> #include <lib$routines.h> . . . status = example(); /* Immediately signal (and quit) if error occurred */ if ((status & STS$M_SUCCESS) == 0) lib$signal(status); /* FAO directive succeeded, output resultant string */ out_buffer[outlen] = '\0'; /* add string terminator to buffer */ puts(out_buffer); /* output the result */

The final example (numbered 11) shows a segment of a HP Fortran for OpenVMS program used to output an ASCII string.

/* SYS$FAO example - illustrating !AC, !AS, !AD, and !/ directives */
#include <string.h>
#include <descrip.h>
#include <starlet.h>

/* MACRO and typedef for counted ASCII strings... */
typedef struct {char len, str[25];} ASCIC;
#define ASCIC_STRING(name, string) ASCIC name = {sizeof(string) - 1, string}

int example()
{
    char    *nod = "Nod";               /* Normal "C" string */
    const int nodlen = strlen(nod); /* Length of "Nod" without '\0' */
    static  ASCIC_STRING(winken, "Winken");
    static  $DESCRIPTOR(blinken, "Blinken");
    static  $DESCRIPTOR(fao_desc, "!/Sailors: !AC !AS !AD");

    return (sys$fao(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    &winken,    /* P1 - Counted ASCII string */
                    &blinken,   /* P2 - ASCII string descriptor */
                    nodlen,     /* P3 - Length of ASCII string */
                    nod));      /* P4 - ASCII string */
}

      

$FAO writes the following string into the output buffer:

<CR><KEY>(LF\TEXT)Sailors: Winken Blinken Nod

The !/ directive provides a carriage-return/line-feed character (shown as <CR><KEY>(LF\TEXT)) for terminal output.

The !AC directive requires the address of a counted ASCII string (p1 argument).

The !AS directive requires the address of a character string descriptor (p2 argument).

The !AD directive requires two parameters: the length of the string to be substituted (p3 argument) and its address (p4 argument).

/*
** SYS$FAO example - illustrating !! and !AS directives,
** repeat count, and output field length
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(jones, "Jones");
    static $DESCRIPTOR(harris, "Harris");
    static $DESCRIPTOR(wilson, "Wilson");
    static $DESCRIPTOR(fao_desc, "Unable to locate !3(8AS)!!");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   &jones,      /* P1 - ASCII string descriptor */
                   &harris,     /* P2 - ASCII string descriptor */
                   &wilson));   /* P3 - ASCII string descriptor */
}
      

$FAO writes the following string into the output buffer:

Unable to locate Jones___Harris__Wilson__!

The !3(8AS) directive contains a repeat count: three parameters (addresses of character string descriptors) are required. $FAO left-justifies each string into a field of eight characters (the output field length specified).

The double exclamation point directive (!!) supplies a literal exclamation point (!) in the output.

If the directive were specified without an output field length, that is, if the directive were specified as !3(AS), the three output fields would be concatenated, as follows:

Unable to locate JonesHarrisWilson!

/* SYS$FAO example - illustrating !UL, !XL, and !SL directives */
#include <descrip.h>
#include <starlet.h>

int example()
{
    int val1 = 200,             /* Values */
        val2 = 300,             /*  for   */
        val3 = -400;            /*   $FAO */

    static $DESCRIPTOR(fao_desc,
                       "Values !UL (Decimal) !XL (Hex) !SL (Signed)");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   val1,        /* P1 - longword value */
                   val2,        /* P2 - longword value */
                   val3));      /* P3 - longword value */
}
      

$FAO writes the following string to the output buffer:

Values 200 (Decimal) 0000012C (Hex) -400 (Signed)

The longword value 200 is converted to decimal, the value 300 is converted to hexadecimal, and the value --400 is converted to signed decimal. The ASCII results of each conversion are placed in the appropriate position in the output string.

Note that the hexadecimal output string has eight characters and is zero-filled to the left. This is the default output length for hexadecimal longwords.

/* SYS$FAOL example - illustrating !UL, !XL, and !SL directives */
#include <descrip.h>
#include <starlet.h>

int example()
{
    static int values[3] = {200, 300, -400};   /* Parameters for $FAOL */
    static $DESCRIPTOR(fao_desc,
                       "Values !UL (Decimal) !XL (Hex) !SL (Signed)");

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    values));   /* Parameter list - longwords */
}
      

$FAOL writes the following string to the output buffer:

Values 200 (Decimal) 0000012C (Hex) -400 (Signed)

The results are the same as the results of Example 3; however, unlike the $FAO directive, which requires each parameter on the call to be specified, the $FAOL directive points to a list of consecutive longwords, which $FAO reads as parameters.

/* SYS$FAOL example - illustrating !UB, !XB, and !SB directives */
#include <descrip.h>
#include <starlet.h>

int example()
{
    static int values[3] = {200, 300, -400};   /* Parameters for $FAOL */
    static $DESCRIPTOR(fao_desc,
                       "Values !UB (Decimal) !XB (Hex) !SB (Signed)");

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    values));   /* Parameter list - longwords */
}
      

$FAO writes the following output string:

Values 200 (Decimal) 2C (Hex) 112 (Signed)

The input parameters are the same as those for Example 4; however, the control string (fao_desc) specifies that byte values are to be converted. $FAO uses the low-order byte of each longword parameter passed to it. The high-order three bytes are not evaluated. Compare these results with the results of Example 4.

/*
** SYS$FAO example - illustrating !XW, !ZW, and !- directives,
** repeat count, and output field length
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(fao_desc,
                       "Hex: !2(6XW) Zero-filled Decimal: !2(-)!2(7ZW)");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   10000,       /* P1 - longword value */
                   9999));      /* P2 - longword value */
}
      

$FAO writes the following string to the output buffer:

Hex:___2710__270F Zero-filled Decimal: 00100000009999

Each of the directives !2(6XW) and !2(7ZW) contains repeat counts and output lengths. First, $FAO performs the !XW directive twice, using the low-order word of the numeric parameters passed. The output length specified is two characters longer than the default output field width of hexadecimal word conversion, so two spaces are placed between the resulting ASCII strings.

The !-- directive causes $FAO to back up over the parameter list. A repeat count is specified with the directive so that $FAO skips back over two parameters; then, it uses the same two parameters for the !ZW directive. The !ZW directive causes the output string to be zero-filled to the specified length (in this example, seven characters). Thus, there are no spaces between the output fields.

/*
** SYS$FAOL example - illustrating !AS, !UB, !%S, and !- directives,
** and variable repeat count
*/
#include <descrip.h>
#include <starlet.h>

/* Layout of argument list for examples */
typedef struct {void    *desc;          /* ASCII string descriptor */
                int     arg[4];         /* Longword arguments */
                } LIST;

$DESCRIPTOR(fao_desc, "!AS received !UB argument!%S: !-!#(4UB)");

int example_a()
{
    static $DESCRIPTOR(orion, "ORION");
    static LIST
        list_a = {&orion,       /* Address of descriptor */
                  3,            /* Number of arguments */
                  10,           /* Argument 1 */
                  123,          /* Argument 2 */
                  210};         /* Argument 3 */

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    &list_a));  /* Parameter list */
}

int example_b()
{
    static $DESCRIPTOR(lyra, "LYRA");
    static LIST
        list_b = {&lyra,        /* ASCII descriptor cast as an (int) */
                  1,            /* Number of arguments */
                  255};         /* Argument 1 */

    return(sys$faol(&fao_desc,  /* Control string for $FAO */
                    &outlen,    /* Pointer for length of output string */
                    &out_desc,  /* Descriptor for output buffer */
                    &list_b));  /* Parameter list */
}
      

In example A, $FAO writes the following string to the output buffer:

ORION received 3 arguments:___10 123 210

In example B, $FAO writes the following string to the output buffer:

LYRA received 1 argument:__255

In each of the examples, the parameter list argument points to a different parameter list; each list contains, in the first longword, the address of a character string descriptor. The second longword begins an argument list, with the number of arguments remaining in the list. The control string uses this second longword twice: first to output the value contained in the longword, and then to provide the repeat count to output the number of arguments in the list (the !- directive indicates that $FAO should reuse the parameter).

The !%S directive provides a conditional plural. When the last value converted has a value not equal to 1, $FAO outputs the character s; if the value is a 1 (as in Example B), $FAO does not output the character s. $FAO outputs the plural character in lowercase since the preceding character was in lowercase.

The output field length defines a width of four characters for each byte value converted, to provide spacing between the output fields.

/*
** SYS$FAO example - illustrating !n*c (repeat character)
** and !%D (date/time) directives
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(fao_desc, "!5*> The time is now: !%D");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   0));         /* P1 - time value, 0 = current time */
}
      

$FAO writes the following string to the output buffer:

>>>>> The time is now: dd-mmm-yyyy hh:mm:ss.cc

where:

dd	is the day of the month
mmm	is the month
yyyy	is the year
hh:mm:ss.cc	is the time in hours, minutes, seconds, and hundredths of a second

The !5*> directive requests $FAO to write five greater-than (>) characters into the output string. Because there is a space after the directive, $FAO also writes a space after the greater-than characters on output.

The !%D directive requires the address of a quadword time value, which must be in the system time format; however, when the address of the time value is specified as 0, $FAO uses the current date and time. For a detailed description of the ASCII date and time string returned, see the discussion of the Convert Binary Time to ASCII String ($ASCTIM) system service.

/*
** SYS$FAO example - illustrating !%D and !%T (with output field lengths),
** and !n directive with variable repeat count
*/
#include <descrip.h>
#include <starlet.h>

int example()
{
    static $DESCRIPTOR(fao_desc, "Date: !11%D!#*_Time: !5%T");

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   0,           /* P1 - time value, 0 = current time */
                   5,           /* P2 - Number of underscores */
                   0));         /* P3 - time value, 0 = current time */
}
      

$FAO writes the following string to the output buffer:

Date: dd-mmm-yyyy_____Time: hh:mm

An output length of 11 bytes is specified with the !%D directive so that $FAO truncates the time from the date and time string, and outputs only the date.

The !#*_ directive requests that the underscore character (_) be repeated the number of times specified by the next parameter. Because p2 is specified as 5, five underscores are written into the output string.

The !%T directive normally returns the full system time. The !5%T directive provides an output length for the time; only the hours and minutes fields of the time string are written into the output buffer.

/*
** SYS$FAO example - illustrating !< and !> (define field width),
** !AC, and !UL directives
*/
#include <descrip.h>
#include <starlet.h>

/* MACRO and typedef for counted ASCII strings... */
typedef struct {char len, str[25];} ASCIC;
#define ASCIC_STRING(name, string) ASCIC name = {sizeof(string) - 1, string}

$DESCRIPTOR(fao_desc, "!32<Variable: !AC Value: !UL!>Total:!7UL");

int example_a()
{
    int     val_a = 334,        /* Current value for variable */
            tot_a = 6554;       /* Current total for variable */

    static ASCIC_STRING(var_a, "Inventory");    /* Counted ASCII string */

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   &var_a,      /* P1 - Variable name */
                   val_a,       /* P2 - Value for variable */
                   tot_a));     /* P3 - Total for variable */
}

int example_b()
{
    int val_b = 280,            /* Current value for variable */
        tot_b = 10750;          /* Current total for variable */

    static ASCIC_STRING(var_b, "Sales");        /* Counted ASCII string */

    return(sys$fao(&fao_desc,   /* Control string for $FAO */
                   &outlen,     /* Pointer for length of output string */
                   &out_desc,   /* Descriptor for output buffer */
                   &var_b,      /* P1 - Variable name */
                   val_b,       /* P2 - Value for variable */
                   tot_b));     /* P3 - Total for variable */
}
      

In example A, $FAO writes the following string to the output buffer:

Variable: Inventory Value: 334__Total:___6554

In example B, $FAO writes the following string to the output buffer:

Variable: Sales Value: 280______Total:__10750

The !25< directive requests an output field width of 25 characters; the end of the field is delimited by the !> directive. Within the field defined are two directives, !AC and !UL. The strings substituted by these directives can vary in length, but the entire field always has 25 characters.

The !7UL directive formats the longword passed in each example (p2 argument) and right-justifies the result in a 7-character output field.

 INTEGER STATUS,
 2       SYS$FAO,
 2       SYS$FAOL

 ! Resultant string
 CHARACTER*80 OUTSTRING
 INTEGER*2    LEN
 ! Array for directives in $FAOL
 INTEGER*4    PARAMS(2)

 ! File name and error number
 CHARACTER*80 FILE
 INTEGER*4    FILE_LEN,
 2            ERROR
 ! Descriptor for $FAOL
 INTEGER*4    DESCR(2)

 ! These variables would generally be set following an error
 FILE = '[BOELITZ]TESTING.DAT'
 FILE_LEN = 18
 ERROR = 25

 ! Call $FAO
 STATUS = SYS$FAO ('File !AS aborted at error !SL',
 2                 LEN,
 2                 OUTSTRING,
 2                 FILE(1:FILE_LEN),
 2                 %VAL(ERROR))
 IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

 TYPE *,'From SYS$FAO:'
 TYPE *,OUTSTRING (1:LEN)

 ! Set up descriptor for filename
 DESCR(1) = FILE_LEN    ! Length
 DESCR(2) = %LOC(FILE)  ! Address
 ! Set up array for directives
 PARAMS(1) = %LOC(DESCR) ! File name
 PARAMS(2) = ERROR       ! Error number
 ! Call $FAOL
 STATUS = SYS$FAOL ('File !AS aborted at error !SL',
 2                  LEN,
 2                  OUTSTRING,
 2                  PARAMS)
 IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

 TYPE *,'From SYS$FAOL:'
 TYPE *,OUTSTRING (1:LEN)

 END
      

This example shows a segment of a HP Fortran for OpenVMS program used to output the following string:

FILE [BOELITZ]TESTING.DAT ABORTED AT ERROR 25

On Alpha systems, converts a binary value into an ASCII character string in decimal, hexadecimal, or octal notation; returns the character string in an output string; and inserts variable character-string data into an output string.

$FAOL_64 interprets the parameter list as a list of quadwords rather than a list of longwords. In all other respects, $FAOL_64 is identical to $FAOL. For all other information about the $FAOL_64 service, refer to the description of $FAO/$FAOL in this manual.

This service accepts 64-bit addresses.

Format

SYS$FAOL_64 ctrstr_64 [,outlen_64 [,outbuf_64 [,quad_prmlst_64]]]

C Prototype

int sys$faol_64 (void *ctrstr_64, unsigned short int *outlen_64, void *outbuf_64, void *quad_prmlst_64);

Arguments

ctrstr_64

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

The 32- or 64-bit address of the control string (64-bit or 32-bit string descriptor).

outlen_64

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

The 32- or 64-bit address of the quadword that contains the output length, in bytes, of the fully formatted output string.

outbuf_64

OpenVMS usage:	char_string
type:	character-coded text string
access:	write only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

The 32- or 64-bit address of a character string descriptor that points to the output buffer into which $FAOL_64 writes the fully formatted output string.

quad_prmlst_64

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

The 32- or 64-bit address of a quadword-aligned array of quadword FAO arguments.

Searches a string for a file specification and parses the components of that file specification.

Format

SYS$FILESCAN srcstr ,valuelst ,[fldflags] ,[auxout] ,[retlen]

C Prototype

int sys$filescan (void *srcstr, void *valuelst, unsigned int *fldflags, void *auxout, unsigned short int *retlen);

Arguments

srcstr

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

String to be searched for the file specification. The srcstr argument is the address of a descriptor pointing to this string.

valuelst

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

Item list specifying which components of the file specification are to be returned by $FILESCAN. The components are the full node specification, primary node name, primary node's access control, secondary node information, device, directory, file name, file type, and version number. The itmlst argument is the address of a list of item descriptors wherein each item descriptor specifies one component. The list of item descriptors is terminated by a longword of 0.

The following diagram depicts a single item descriptor:

The following table defines the item descriptor fields:

fldflags

The $FSCNDEF macro defines a symbolic name for each significant flag bit. The following table shows the file specification component that corresponds to the symbolic name of each flag bit:

The fldflags argument is optional. When you want to know which components of a file specification are present in a string but do not need to know the contents or length of these components, specify fldflags instead of valuelst.

auxout

When you specify an auxiliary output buffer, $FILESCAN copies the entire source string, with quotation information reduced and simplified for only the primary node, into the auxiliary output buffer.

When the auxiliary output buffer is provided, all addresses returned in the item list point to locations in the auxiliary output buffer.

retlen

Item Codes

FSCN$_DEVICE

Returns the length and starting address of the device name. The device name includes the single colon (:).

FSCN$_DIRECTORY

Returns the length and starting address of the directory name. The directory name includes the brackets ([ ]) or angle brackets (< >).

FSCN$_FILESPEC

Returns the length and starting address of the full file specification. The full file specification contains the node, device, directory, name, type, and version.

FSCN$_NAME

Returns the length and starting address of the file name. The file name includes no syntactical elements.

$FILESCAN also returns the length and starting address of a quoted file specification following a node specification (as in the specification NODE::"FILE-SPEC"). The beginning and ending quotation marks are included.

If there is no name component but there is either a type or version component, the flags argument for FSCN$V_NAME is set and the address field contains a nonzero pointer (pointing to the period for the type component); however, the length field does contain zero.

FSCN$_NODE

Returns the length and starting address of the full node specification. The full node specification includes the primary node name, the primary node's access control string, any secondary node information, and the final double colon (::).

FSCN$_NODE_ACS

Returns the length and starting address of the primary access control string. If multiple nodes are specified, the primary access control string represents the control information (if present) for the first node specified. The primary access control string does not contain the double colon (::), but does contain the double quotes.

FSCN$_NODE_PRIMARY

Returns the length and starting address of the primary node name. If multiple nodes are specified, the primary node name represents the first node specification. The node name does not include the double colon (::) or any access control information. If an auxiliary output buffer is specified, quotation information is reduced and simplified for only the primary node.

FSCN$_NODE_SECONDARY

Returns the length and starting address of any secondary node information. The secondary node string contains any node information referring to additional nodes, including the final double colon (::), as well as any access control strings (if present) for the additional nodes.

FSCN$_ROOT

Returns the length and starting address of the root directory string. The root directory name string includes the brackets ([ ]) or angle brackets (< >).

FSCN$_TYPE

Returns the length and starting address of the file type. The file type includes the preceding period (.).

FSCN$_VERSION

Returns the length and starting address of the file version number. The file version number includes the preceding period (.) or semicolon (;) delimiter.

Description

The Scan String for File Specification service searches a string for a file specification and parses the components of that file specification. When $FILESCAN locates a partial file specification (for example, DISK:[FOO]), it returns the length and starting address of those components that were requested in the item list and were found in the string. If a component was requested in the item list but not found in the string, $FILESCAN returns a length of 0 and an address of 0 to the component address field in the item descriptor for that component (see item code FSCB$_NAME for exception).

The information returned about all of the individual components describes the entire contiguous file specification string. For example, to extract only the file name and file type from a full file specification string, you can add the length of these two components and use the address of the first component (file name). However, the specific node name and node control strings extracted using the FSCN$_NODE_PRIMARY and FSCN$_NODE_ACS item codes cannot be recombined because the double colon (::) is not included in either string.

If an auxiliary output buffer is provided, $FILESCAN copies the entire source string, removing and reducing quotation marks from the primary node name.

The $FILESCAN service does not perform comprehensive syntax checking. Specifically, it does not check that a component has a valid length.

However, $FILESCAN does check for the following information:

• The component must have required syntactical elements; for example, a directory component must be enclosed in brackets ([]), and a node name must be followed by an unquoted double colon (::).
• The component must not contain invalid characters. Invalid characters are specific to each component. For example, a comma (,) is a valid character in a directory component but not in a file type component.
• Spaces, tabs, and carriage returns are permitted within quoted strings, but are invalid anywhere else.
• If a node name contains a space, tab, double quote ("), or double colon (::), then the node name must be quoted.

The node component of a file specification contains one or more node specifications. A node specification is a node name, followed by an optional access control string, followed by a double colon (::). A node name is either a standard name or a quoted name.

If the node name contains quotation marks, the quotes must be doubled ("") and the entire node name quoted. For example, the node abc"def" would be represented as "abc""def""". An access control string is a quoted string containing a user name, an optional password, and an optional account name. Note that the double quotes are only used to differentiate between a primary node name containing embedded quotes and the access control string. See the Example section for the proper use of this syntax.

Invalid characters are treated as terminators. For example, if $FILESCAN encounters a space within a file name component, it assumes that the space terminates the full file specification string.

For node names, a space, tab, double quote ("), and comma (,) are treated as terminators and must be quoted if they are part of the node name. In addition, the double colon (::) and the trailing colon (for example, NODE:) are treated as terminators and must also be quoted if they are part of the node name.

The $FILESCAN service recognizes the DEC Multinational alphabetical characters (such as à) as alphanumeric characters.

The $FILESCAN service accepts extended (ODS-5) file names. The parsing types and names are independent of the volume they reside on; therefore, if the device name points to an ODS-2 volume, you can specify an ODS-5 file name. Refer to the Guide to OpenVMS File Applications for information on ODS-5 file specifications.

The $FILESCAN service does not (1) assume default values for unspecified file specification components, (2) perform logical name translation on components, (3) perform wildcard processing, or (4) perform directory lookups.

Required Access or Privileges

None

Required Quota

None

Related Services

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service could not read the string pointed to by the srcstr argument; or it could not write to an item descriptor in the item list specified by the valuelst argument; or it could not write to the specified auxiliary output buffer; or the retlen argument could not be written.
SS$_BADPARAM	The item list contains an invalid item code.

Example

! The following is a C example for using the $FILESCAN service.

#include <perror.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <descrip.h>
#include <iledef.h>
#include <fscndef.h>
#include <starlet.h>
#include <ssdef.h>

//
// Build table of names.  Verify positions in table.
//

#if FSCN$_FILESPEC != 1
#error "table assumption for FILESPEC is invalid."
#endif
#if FSCN$_NODE_SECONDARY != 11
#error "table assumption for NODE_SECONDARY is invalid."
#endif

char *name_field[] = {
                "",
                "FILESPEC",
                "NODE",
                "DEVICE",
                "ROOT",
                "DIRECTORY",
                "NAME",
                "TYPE",
                "VERSION",
                "NODE_PRIMARY",
                "NODE_ACS",
                "NODE_SECONDARY" } ;

typedef struct fldflags FLDFLAGS ;

main(int argc, char *argv[] )
{

    int status ;
    int field_flags ;
    char *filename;
    struct dsc$descriptor_s file_name = { 0 } ;
    struct dsc$descriptor_s output_string = { 0 } ;
    short retlen ;
    int i ;
    ile2 itmlst[] = {
                {0, FSCN$_FILESPEC, 0},
                {0, FSCN$_NODE, 0},
                {0, FSCN$_DEVICE, 0},
                {0, FSCN$_ROOT, 0},
                {0, FSCN$_DIRECTORY, 0},
                {0, FSCN$_NAME, 0},
                {0, FSCN$_TYPE, 0},
                {0, FSCN$_VERSION, 0},
                {0, FSCN$_NODE_PRIMARY, 0},
                {0, FSCN$_NODE_ACS, 0},
                {0, FSCN$_NODE_SECONDARY, 0},
                { 0, 0, 0 } } ;


    output_string.dsc$w_length = 4096 ;
    if ((output_string.dsc$a_pointer = malloc(4096)) == NULL) {
        perror("Malloc Failure");
        exit(0) ;
        }
    if ((file_name.dsc$a_pointer = filename = malloc(4096)) == NULL) {
        perror("Malloc Failure");
        exit(0) ;
        }

    for( ;; ) {

        printf("\nEnter file name: ") ;
        if (gets(filename) == NULL)
            break ;

        file_name.dsc$w_length = strlen(filename) ;

        status = sys$filescan( &file_name, itmlst, &field_flags,
                                &output_string, &retlen) ;

        if (!(status&1)) exit(status) ;

        if ((itmlst[0].ile2$ps_bufaddr != NULL) && (retlen != 0))
            printf("The file name returned is %.*s\n", retlen,
                (char*)itmlst[0].ile2$ps_bufaddr ) ;
        else
            printf("There is no file name returned for FSCN$_FILESPEC\n");

        for( i = 0; i < FSCN$_NODE_SECONDARY; i++) {
        if ((int)field_flags & 1<<i)
            printf("The component %s is present: %.*s\n", name_field[i+2],
                            itmlst[i+1].ile2$w_length,
                                (char*)itmlst[i+1].ile2$ps_bufaddr ) ;
        }
    }
    exit(status) ;
}


      

This C example demonstrates the use of the $FILESCAN service.

Following is an example of the program output:

$ RUN TEST_SCAN Enter file name: abc"def" The file name is abc"def" The component NAME is present: abc Enter file name: "abc""def""" There is no file name returned for FSCN$_FILESPEC Enter file name: "abc""def""":: The file name is abc"def":: The component NODE is present: abc"def":: The component NODE_PRIMARY is present: abc"def" Enter file name: "abc""def""""user password":: The file name is abc"def""user password":: The component NODE is present: abc"def""user password":: The component NODE_PRIMARY is present: abc"def" The component NODE_ACS is present: "user password" Enter file name: abc"def":: The file name is abc"def":: The component NODE is present: abc"def":: The component NODE_PRIMARY is present: abc The component NODE_ACS is present: "def" Enter file name: "abc""def""""system password"::[dir.1]a^ ^".file;1 The file name returned is abc"def""system password"::[dir.1]a^ ^".file;1 The component NODE is present: abc"def""system password":: The component DIRECTORY is present: [dir.1] The component NAME is present: a^ ^" The component TYPE is present: .file The component VERSION is present: ;1 The component NODE_PRIMARY is present: abc"def" The component NODE_ACS is present: "system password"

The Find service locates a specified record in a file and returns its record file address in the RAB$W_RFA field of the RAB. The Find service can be used with all file organizations.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Returns the identifiers held by a specified holder.

Format

SYS$FIND_HELD holder ,[id] ,[attrib] ,[contxt]

C Prototype

int sys$find_held (struct _generic_64 *holder, unsigned int *id, unsigned int *attrib, unsigned int *contxt);

Arguments

holder

OpenVMS usage:	rights_holder
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Holder whose identifiers are to be found when $FIND_HELD completes execution. The holder argument is the address of a quadword data structure containing the holder identifier. This quadword data structure consists of a longword containing the holder UIC, followed by a longword containing the value 0.

id

OpenVMS usage:	rights_id
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Identifier value found when $FIND_HELD completes execution. The id argument is the address of a longword containing the identifier value with which the holder is associated.

attrib

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Attributes associated with the holder returned in id when $FIND_HELD completes execution. The attrib argument is the address of a longword containing a bit mask specifying the attributes.

Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The symbols are defined in the system macro library ($KGBDEF). The following are the symbols for each bit position:

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows the holder to charge resources, such as disk blocks, to the identifier.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

contxt

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

Context value used when repeatedly calling $FIND_HELD. The contxt argument is the address of a longword used while searching for all identifiers. The context value must be initialized to 0, and the resulting context of each call to $FIND_HELD must be presented to each subsequent call. After contxt is passed to $FIND_HELD, you must not modify its value.

Description

The Find Identifiers Held by User service returns a list of the identifiers that another identifier holds. Use the $FIND_HELD service to construct the process rights when a user logs in (unless that process has read access to the rights database). To determine all the identifiers held by the specified holder, call $FIND_HELD repeatedly until it returns the status code SS$_NOSUCHID. When SS$_NOSUCHID is returned, $FIND_HELD has returned all the identifiers, cleared the context value, and deallocated the record stream.

If you complete your calls to $FIND_HELD before SS$_NOSUCHID is returned, use $FINISH_RDB to clear the context value and deallocate the record stream.

Note that, when you use wildcards with this service, the records are returned in the order that they were originally written because the first record is located on the basis of the holder ID. Thus, all the target records have the same holder ID or, in other words, they have duplicate keys, which leads to retrieval in the order in which they were written.

Required Access or Privileges

Read access to the rights database is required to obtain information about identifiers held by other users.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The id argument cannot be written by the service, or the holder, attrib, or contxt argument cannot be read by the service.
SS$_IVCHAN	The contents of the contxt longword are not valid.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT	The format of the specified holder identifier is invalid.
SS$_NOIOCHAN	No more rights database context streams are available.
SS$_NOSUCHID	The specified holder identifier does not exist, or no further identifiers are held by the specified holder.
RMS$_PRV	You do not have read access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

Returns the holder of a specified identifier.

Format

SYS$FIND_HOLDER id ,[holder] ,[attrib] ,[contxt]

C Prototype

int sys$find_holder (unsigned int id, struct _generic_64 *holder, unsigned int *attrib, unsigned int *contxt);

Arguments

id

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

Binary identifier value whose holders are found by $FIND_HOLDER. The id argument is a longword containing the binary identifier value.

holder

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

Holder identifier returned when $FIND_HOLDER completes execution. The holder argument is the address of a quadword containing the holder identifier. The first longword contains the UIC of the holder with the high-order word containing the group number and the low-order word containing the member number. The second longword contains the value 0.

attrib

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Mask of attributes associated with the holder record specified by holder. The attrib argument is the address of a longword containing the attribute mask.

Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The symbols are defined in the system macro library ($KGBDEF). The following are the symbols for each bit position:

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET RIGHTS_LIST. For more information on SET RIGHTS_LIST, refer to the HP OpenVMS DCL Dictionary.
KGB$V_NOACCESS	Makes any rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows the holder of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM	Allows holders of an identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

contxt

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

Context value used while searching for all the holders of the specified identifier when executing $FIND_HOLDER. The contxt argument is the address of a longword containing the context value. When calling $FIND_HOLDER repeatedly, contxt must be set initially to 0 and the resulting context of each call to $FIND_HOLDER must be presented to each subsequent call. After the argument is passed to $FIND_HOLDER, you must not modify its value.

Description

The Find Holder of Identifier service returns the holder of the specified identifier. To determine all the holders of the specified identifier, you call SYS$FIND_HOLDER repeatedly until it returns the status code SS$_NOSUCHID, which indicates that $FIND_HOLDER has returned all identifiers, cleared the context longword, and deallocated the record stream. If you complete your calls to $FIND_HOLDER before SS$_NOSUCHID is returned, you use the $FINISH_RDB service to clear the context value and deallocate the record stream.

Note that when you use wildcards with this service, the records are returned in the order in which they were originally written. (This action results from the fact that the first record is located on the basis of the identifier. Thus, all the target records have the same identifier or, in other words, they have duplicate keys, which leads to retrieval in the order in which they were written.)

Required Access or Privileges

Read access to the rights database is required to obtain information about identifiers marked HOLDER_HIDDEN.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The id argument cannot be read by the caller, or the holder, attrib, or contxt argument cannot be written by the caller.
SS$_IVCHAN	The contents of the contxt longword are not valid.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT	The specified identifier or holder identifier is of invalid format.
SS$_NOIOCHAN	No more rights database context streams are available.
SS$_NOSUCHID	The specified identifier does not exist in the rights database, or no further holders exist for the specified identifier.
RMS$_PRV	The user does not have read access to the rights database.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

Deallocates the record stream and clears the context value used with $FIND_HELD, $FIND_HOLDER, or $IDTOASC.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$FINISH_RDB contxt

C Prototype

int sys$finish_rdb (unsigned int *contxt);

Argument

contxt

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Context value to be cleared when $FINISH_RDB completes execution. The contxt argument is a longword containing the address of the context value.

Description

The Terminate Rights Database Context service clears the context longword and deallocates the record stream associated with a sequence of rights database lookups performed by the $IDTOASC, $FIND_HOLDER, and $FIND_HELD services.

If you repeatedly call $IDTOASC, $FIND_HOLDER, or $FIND_HELD until SS$_NOSUCHID is returned, you do not need to call $FINISH_RDB because the record stream has already been deallocated and the context longword has already been cleared.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The contxt argument cannot be written by the caller.
SS$_IVCHAN	The contents of the contxt longword are not valid.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

The Flush service writes out all modified I/O buffers and file attributes associated with the file. This ensures that all record activity up to the point at which the Flush service executes is actually reflected in the file.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about this service.

Causes an Exit ($EXIT) service call to be issued on behalf of a specified process.

Format

SYS$FORCEX [pidadr] ,[prcnam] ,[code]

C Prototype

int sys$forcex (unsigned int *pidadr, void *prcnam, unsigned int code);

Arguments

pidadr

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

Process identification (PID) of the process to be forced to exit. The pidadr argument is the address of a longword containing the PID.

The pidadr argument can refer to a process running on the local node or a process running on another node in the OpenVMS Cluster system.

The pidadr argument is optional but must be specified if the process that is to be forced to exit is not in the same UIC group as the calling process.

prcnam

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Process name of the process that is to be forced to exit. The prcnam argument is the address of a character string descriptor pointing to the process name string. A process running on the local node can be identified with a 1- to 15-character string. To identify a process on a particular node in a cluster, specify the full process name, which includes the node name as well as the process name. The full process name can contain up to 23 characters.

The prcnam argument can be used only on behalf of processes in the same UIC group as the calling process. To force processes in other groups to exit, you must specify the pidadr argument. This restriction exists because the operating system interprets the UIC group number of the calling process as part of the specified process name; the names of processes are unique to UIC groups.

code

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

Completion code value to be used as the exit parameter. The code argument is a longword containing this value. If you do not specify the code argument, the value 0 is passed as the completion code.

Description

The Force Exit service causes an Exit service call to be issued on behalf of a specified process.

If you specify neither the pidadr nor the prcnam argument, the caller is forced to exit and control is not returned.

If the longword at address pidadr is 0, the PID of the target process is returned.

The Force Exit system service requires system dynamic memory.

The image executing in the target process follows normal exit procedures. For example, if any exit handlers have been specified, they gain control before the actual exit occurs. Use the Delete Process ($DELPRC) service if you do not want a normal exit.

When a forced exit is requested for a process, a user-mode asynchronous system trap (AST) is queued for the target process. The AST routine causes the $EXIT service call to be issued by the target process. Because the AST mechanism is used, user mode ASTs must be enabled for the target process, or no exit occurs until ASTs are reenabled. Thus, for example, a suspended process cannot be stopped by $FORCEX. The process that calls $FORCEX receives no notification that the exit is not being performed.

If an exit handler resumes normal processing, the process will not exit. In particular, if the program is written in Ada and there is a task within the program that will not terminate, the program will not exit.

The $FORCEX service completes successfully if a force exit request is already in effect for the target process but the exit is not yet completed.

Required Access or Privileges

Depending on the operation, the calling process might need a certain privilege to use $FORCEX:

• You need GROUP privilege to force an exit for a process in the same group that does not have the same UIC as the calling process.
• You need WORLD privilege to force an exit for any process in the system.

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The process name string or string descriptor cannot be read by the caller, or the process identification cannot be written by the caller.
SS$_INCOMPAT	The remote node is running an incompatible version of the operating system.
SS$_INSFMEM	The system dynamic memory is insufficient for the operation.
SS$_IVLOGNAM	The process name string has a length equal to 0 or greater than 15.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.
SS$_NOPRIV	The process does not have the privilege to force an exit for the specified process.
SS$_NOSUCHNODE	The process name refers to a node that is not currently recognized as part of the cluster.
SS$_REMRSRC	The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)
SS$_UNREACHABLE	The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)