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 areinaccessible, 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. Theinadr argument is the address of a 2-longword arraycontaining, in order, the starting and ending process virtualaddresses. If the starting and ending virtual addresses are the same, asingle page is deleted. The addresses are adjusted up or down to fallon CPU-specific page boundaries. Only the virtual page number portionof each virtual address is used; the low-order byte-within-page bitsare ignored.

The $DELTVA service deletes pages starting at the address contained inthe second longword of the inadr argument and endingat the address in the first longword. Thus, if you use the same addressarray for both the Create Virtual Address Space ($CRETVA) and the$DELTVA services, the pages are deleted in the reverse order from whichthey 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 $DELTVAhas deleted. The retadr argument is the address of a2-longword array containing, in order, the starting and ending processvirtual 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. Theacmode argument is a longword containing the accessmode.

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 byan access mode equal to or less privileged than the access mode of thecalling process.

Description

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

If an error occurs while pages are being deleted, theretadr argument specifies the pages that weresuccessfully deleted before the error occurred. If no pages aredeleted, 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'svirtual address space. Upon successful completion of the service, thedeleted pages are inaccessible, and references to them cause accessviolations.

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 VAspace.

The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro inSTARLET.MLB define a symbolic name for each of the three defaultregions 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 bespecified. Also, the region ID that a virtual address is in can beobtained by calling the $GET_REGION_INFO service, specifying theVA$_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 specifiedaddress must be a CPU-specific page aligned address. If theregion_id_64 argument specifies a shared page tableregion or if the start_va_64 argument lies within ashared page table region, the specified address must be a CPU-specificpage 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 specifiedmust be a multiple of CPU-specific pages. If the virtual address spaceis being deleted from a shared page table region, the specified lengthmust be page table page aligned or include the last page in amemory-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. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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 byan access mode equal to or less privileged than the access mode of thecalling 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 addressrange. The return_va_64 argument is the 32- or 64-bitvirtual 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 intowhich the $DELTVA_64 service returns the length in bytes of the virtualaddress range deleted.

Description

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

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

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments. If a condition value other than SS$_ACCVIO is returned, thereturned address and returned length indicate the pages that weresuccessfully deleted before the error occurred. If no pages weredeleted, the return_va_64 argument will contain thevalue --1, and a value cannot be returned in the memorylocation 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; orcancels an ungranted lock request. The calling process must havepreviously acquired the lock or queued the lock request by calling theEnqueue 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. Thelkid argument specifies this lock identification.

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

When you specify the LCK$M_DEQALL flag in the flagsargument, different values (or no value) for the lkidargument 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) andthe LCK$M_DEQALL flag is not set, the $DEQ service returns the invalidlock 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 bedequeued. The valblk argument is the 32- or 64-bitaddress (on Alpha systems) or the 32-bit (on VAX systems) of the16-byte lock value block. When you specify the LCK$M_DEQALL flag, youcannot use this argument.

When a protected write (PW) or exclusive (EX) mode lock is beingdequeued and you specify a lock value block in thevalblk argument, the contents of that lock value blockare written to the lock value block in the lock database. Further, ifthe lock value block in the lock database was marked as invalid, thatcondition 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 acmodeargument is a longword containing the access mode.

The acmode argument is valid only if the LCK$M_DEQALLflag of the flags argument is set. The $PSLDEF macrodefines 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 andthe specified acmode argument. The maximized accessmode is the less privileged of the caller's access mode and theacmode argument. If you do not specify theacmode argument, $DEQ uses the caller's access mode.Only those locks with an access mode that is equal to or less than themaximized 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. Theflags argument is a longword bit mask that is thelogical OR of each bit set, where each bit corresponds to an option.

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

A symbolic name for each flag bit is defined by the $LCKDEF macro. Thefollowing 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 andwaiting lock requests. The calling process must have previouslyacquired the lock or queued the lock request by calling the EnqueueLock Request ($ENQ) service.

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

When dequeuing a granted lock, the $DEQ service returns the conditionvalue 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 thecondition 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 $DEQservice returns the condition value SS$_NORMAL and the followingspecific 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 beingdequeued and you specify a lock value block in thevalblk argument, the contents of that lock value blockare written to the lock value block in the lock database.

If you specify the LCK$M_INVVALBLK flag in the flagsargument and the lock mode of the lock being dequeued is PW or EX, thelock value block in the lock database is marked as invalid whether ornot a lock value block was specified in the valblkargument.

The $DEQ, $ENQ, $ENQW, and $GETLKI services together provide the userinterface to the lock management facility. For additional informationabout lock management, refer to the descriptions of these otherservices 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 devicename. 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 whichinformation is desired. The chan argument is a wordcontaining this number.

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

If you specify neither chan nordevnam, $DEVICE_PATH_SCAN uses a default value of 0for 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 pathinformation. The devnam argument is the address of acharacter string descriptor pointing to this name string.

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

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

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

If you specify neither chan nordevnam, $DEVICE_PATH_SCAN uses a default value of 0for 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 bereturned. The itmlst argument is the address of a listof item descriptors, each of which describes an item of information.The list of item descriptors is terminated by a longword of 0. Thefollowing diagram depicts the format of a single item descriptor:

See the itmlst argument in the $GETDVI system servicedescription for information on the meaning of these fields in the itemlist.

contxt

nullarg

Item Code

DPS$_MP_PATHNAME

When you specify DPS$_MP_PATHNAME, $DEVICE_PATH_SCAN returns the nameof one of the Multipath I/O paths connecting to the device named in thedevnam argument. When the value of thecontxt argument is 0, the path name for the firstestablished path will be returned. On subsequent calls, with a non-zerocontxt value, the path names of the remainingavailable paths to the device will be returned.

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

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

The DPSDEF macro contains this item code.

Description

The Scan for Device Paths service returns I/O path information for agiven I/O channel or device name. Each call to $DEVICE_PATH_SCAN willreturn information on a different I/O path connecting with the devicespecified in the chan or devnamarguments.

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

Once the service has returned information on all paths to the nameddevice, any further calls that use the final contxtvalue 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 searchcriteria.

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_devnamargument is the address of a character string descriptor pointing to abuffer into which $DEVICE_SCAN writes the name of the first or nextdevice that matches the specified search criteria. The maximum size ofany 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. Theretlen 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. Thesearch_devnam argument accepts the standard wildcardcharacters, the asterisk (*), which matches any sequence of characters,and the percent sign (%), which matches any one character. If thesearch_devnam argument does not include a wildcardcharacter, an exact match is used for comparison. For example, to matchall unit 0 DU devices on any controller, specify*DU%0. This string is compared to the most complete devicename (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 namesfor return by $DEVICE_SCAN. The itmlst argument is theaddress of a list of item descriptors, each of which describes onesearch criterion. The list of item descriptors is terminated by alongword 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, thedevice 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, thedevice type for which $DEVICE_SCAN is going to search. The $DCDEF macrodefines 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 tospecify the device type being searched for.

Description

The Scan for Devices system service returns the names of all devicesthat 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 valueis used to continue multiple calls to $DEVICE_SCAN.

$DEVICE_SCAN allows wildcard searches based on device names, deviceclasses, and device types. It also provides the ability to perform awildcard 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 selectioncriteria:

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 actualdeletion of the global section takes place when all processes that havemapped 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. Theflags argument is a longword value. A value of 0 (thedefault) specifies a group global section; a value of SEC$M_SYSGBLspecifies a system global section; a value of SEC$M_SHMGS on an OpenVMSGalaxy 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 gsdnamargument is the address of a character string descriptor pointing tothis name string.

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

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

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

Names are first subject to a logical name translation, after theapplication 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 nottranslate, the name specified by the caller is used as the name of thesection.

Additional information on logical name translations and on section nameprocessing 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 globalsection to be deleted and the matching criteria to be applied. Theident argument is the 32- or 64-bit address (on Alphasystems) or the 32-bit address (on VAX systems) of a quadword structurecontaining three fields.

The version number is in the second longword. The version numbercontains two fields: a minor identification in the low-order 24 bitsand a major identification in the high-order 8 bits. Values for thesefields can be assigned by installation convention to differentiateversions of global sections. If you specify no version number whencreating a section, processes that specify a version number whenmapping cannot access the global section.

The first longword specifies, in its low-order 3 bits, the matchingcriteria. The valid values, the symbolic names by which they can bespecified, 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 versionnumber and match control fields default to 0.

Description

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

After a global section has been marked for deletion, any process thatattempts to map it receives the warning return status codeSS$_NOSUCHSEC.

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

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

Required Access or Privileges

Depending on the operation, the calling process might need one or moreof 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'svirtual address space. To do this, the process should call the DeleteVirtual Address Space ($DELTVA or $DELTVA_64) service, which deletesthe 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/Obuffers 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 devnamargument is the address of a character string descriptor pointing tothe device name string. The string can be either a physical device nameor a logical name. If it is a logical name, it must translate to aphysical 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 abit, when set, selects the corresponding option. Each bit has asymbolic 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 fromyour 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, $DISMOUdoes not mark the volume for dismounting (because the volume must havebeen mounted shared). In this case, the total effect for the issuingprocess is that the process is denied access to the volume and alogical name entry is deleted.

If the mount count equals 0 after being decremented, $DISMOU marks thevolume for dismounting. After marking the volume for dismounting,$DISMOU waits until the volume is idle before dismounting it. A nativevolume is idle when no user has an open file to the volume, and aforeign 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 /GROUPor /SYSTEM qualifier.

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

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

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

By specifying the DVI$_DEVCHAR item code in a call to $GETDVI, you canlearn 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 isset). If DEV$V_MNT is clear or if DEV$M_DMT is set, the mount count is0.

Required Access or Privileges

Depending on the operation, the calling process might need one of thefollowing 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 fileand places this information in fields in the FAB, in XABs chained tothe 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 shortint buffer_sizes [4], void *proxy_node, void *proxy_user, void*default_user, unsigned int *local_users, unsigned int flags, unsignedint *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 beingrequested. The rem_node argument is the address of acharacter-string descriptor pointing to the remote node name string.

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

Asterisk (*) and percent sign (%) wildcards are allowed for the remotenode specification. If you specify wildcards for therem_node argument, the server searches the entireproxy database for matches to the remote node and remote user youspecified. If a match is found, information about the matched proxy isreturned. See the Description section for additional details onretrieving 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 beingrequested. The rem_user argument is the address of acharacter-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 ([ ]). Anylowercase characters specified are automatically converted to uppercase.

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

Asterisk (*) and percent sign (%) wildcards are allowed for the remoteuser specification. If you specify wildcards for therem_user argument, the server searches the entireproxy database for matches to the remote node and remote user youspecified. If a match is found, information about the matched proxy isreturned. See the Description section for information about retrievinginformation 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. Thebuffer_sizes argument is the address of an array offour 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 nodelength field returned in the buffer specified by thebuffer_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 userlength field returned in the buffer specified by thebuffer_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 userlength field in the buffer specified by thebuffer_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 mustbe able to contain up to 16 user name buffers; therefore, the bufferlength must be 576 bytes.

The number of elements returned in the buffer is specified in the localusers count field returned in the buffer specified by thebuffer_sizes argument.

flags

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

context

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

Contexts become invalid after one-half hour of non-use. This means thatif you call the $DISPLAY_PROXY service with a wildcardrem_node or rem_user, and do not callthe service to get the next matching record within one-half hour, thecontext becomes invalid. If the context has become invalid, you muststart your search of the proxy database over from its beginning byresetting the context to 0.

Description

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

Wildcards can be specified for the rem_node andrem_user arguments. Because $DISPLAY_PROXY can returninformation about only one matching proxy at a time, you must call thisservice repeatedly with the context argument toretrieve information about all matching proxies. $DISPLAY_PROXY returnsSS$_NOMOREITEMS when information about all of the matching proxies hasbeen returned. No proxy information is returned from the call thatreturns the SS$_NOMOREITEMS status.

Required Access or Privileges

The caller must have SYSPRV privilege or a UIC group less than or equalto 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. Thename argument is the address of a character stringdescriptor pointing to the name of the cluster.

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

Description

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

If the cluster has already been deleted or does not exist, the $DLCEFCservice 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) clerkallows client applications to store resource names and addresses.

The $DNS system service completes asynchronously; that is, it returnsto the client immediately after making a name service call. The statusreturned to the client call indicates whether a request wassuccessfully queued to the name service.

The DIGITAL Distributed Name Service Clerk Wait ($DNSW) system serviceis the synchronous equivalent of $DNS. $DNSW is identical to $DNS inevery way except that $DNSW returns to the caller after the operationcompletes.

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. Theefn argument is a longword containing this number. Theefn argument is optional; if not specified, event flag0 is used.

When $DNS begins execution, it clears the event flag. Even if theservice encounters an error and completes without queuing a nameservice 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. Thefunc argument is a longword containing this functioncode.

A single call to $DNS can specify one function code. Most functioncodes require or allow for additional information to be passed in thecall 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 functionspecified by the func argument. Theitmlst argument is the address of the item list. Theitem list consists of one or more item descriptors, each of which isthree longwords.

The descriptors can be in any order in the item list. Each itemdescriptor specifies an item code. Item codes are specified as eitherinput or output parameters. Input parameters modify functions, setcontext, or describe the information to be returned. Output parametersreturn the requested information. The item list is terminated by alongword of 0.

The item list is a standard format item list. The following figuredepicts 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 andDNS$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 qualifyingstatus. 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 andwrite 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. Thisrequest 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 writeaccess 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, orclearinghouse in the namespace. Specify the target to which the softlink points in the DNS$_TARGETNAME item code. Use the DNS$_RESOLVE_NAMEfunction code to check the existence of the target.

You must have write or control access to the directory in which thesoft 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 objecthas 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$ACSattributes. The client application supplies the DNS$Class andDNS$ClassVersion attributes. You can add attributes using theDNS$_MODIFY_ATTRIBUTE function.

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

If specified, DNS$_OUTCTS holds the creation timestamp of the newlycreated 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 willreside.

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 orcontrol 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$_OUTATTRIBUTESETthat are associated with the directory, object, soft link, orclearinghouse. Specify the entry type in the DNS$_LOOKINGFOR item code.The function returns either DNS$K_SET or DNS$K_SINGLE along with theset of attribute names.

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

The DECdns clerk enumerates attributes in alphabetical order. Areturn status of DNS$_MOREDATA implies that not all attributes havebeen enumerated. You should make further calls, settingDNS$_CONTEXTVARNAME to the last attribute in the set returned, untilthe 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, orclearinghouse.

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 simplename that uses a wildcard. The DECdns clerk matches the inputagainst child directory entries in the specified directory.

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

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

The clerk enumerates child directories in alphabetical order. If thecall returns DNS$_MOREDATA, not all child directories have beenenumerated and the client should make further calls, settingDNS$_CONTEXTVARNAME to the last child directory in the set returned,until the procedure returns SS$_NORMAL. Subsequent calls return thechild directories, starting with the directory specified inDNS$_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 canuse a wildcard, and a class name that uses a wildcard. TheDECdns clerk matches these against objects in the directory. Ifa wildcard and class filter are not specified, all objects in thedirectory are returned.

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

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

The clerk enumerates objects in alphabetical order. If the call returnsDNS$_MOREDATA, not all objects have been enumerated and the clientshould make further calls, setting DNS$_CONTEXTVARNAME to the lastobject in the set returned, until the procedure returns SS$_NORMAL. Ifthe class filter is specified, only those objects of the specifiedclasses 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 wildcardedsimple name. The DECdns clerk matches these against soft linksin the directory. It returns (in DNS$_OUTSOFTLINKS) a set consisting ofsimple names of soft links in the directory that match the wildcardedname. If no soft link entries match the wildcard or the directorycontains no soft links, a null set is returned.

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

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

The clerk enumerates soft links in alphabetical order. If the callreturns DNS$_MOREDATA, not all matching soft links have been enumeratedand the client should make further calls, setting DNS$_CONTEXTVARNAMEto the last soft link in the set returned, until the procedure returnsSS$_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 instring format. To prevent the namespace nickname from being included inthe 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 thenamespace. 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 avalue in the DNS$_MODVALUE item code. If you do not specify a value fora 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 clerkcreates the attribute with an empty set.

To delete an attribute value, use the DNS$_MODVALUE item code to removethe specified value from an attribute set. If you do not specify theitem 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, softlink, or clearinghouse whose attribute is being modified, depending onwhether 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 andsynchronizes the copies to recover as much of the original directorystate as possible. You can also use the function to change a replicatype 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 storesecondary and read-only replicas (DNS$_SECCHSET and DNS$_READCHSET).

You must have control access to the parent directory and write accessto each clearinghouse for which the replica type will be changed fromits 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 itsequivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTR itemcode, the clerk examines the name specified in DNS$_FROMSTRINGNAME forinvalid characters. The buffer returns the address of the character inthe 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 toits equivalent in opaque format. If you specify the DNS$_NEXTCHAR_PTRitem code, the clerk examines the name specified in DNS$_FROMSTRINGNAMEfor invalid characters. The buffer returns the address of the characterin 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 thevalues of the specified attribute.

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

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

If the client sets the DNS$_MAYBEMORE item code to 1, the name serviceattempts to make subsequent DNS$_READ_ATTRIBUTE calls for the samevalue 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 linkis deleted. Any DECdns name that is referenced by the soft linkremains unaffected by the operation.

You must have delete access to the soft link, or delete or controlaccess 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 writeaccess 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 functionreturns the full name of the target.

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

If the application provides a name that does not contain any softlinks, DNS$_NOTLINKED status is returned. If the target of any of thechain of soft links followed does not exist, the DNS$_DANGLINGLINKstatus is returned. To obtain the target of any particular soft link,use the DNS$_READ_ATTRIBUTE function with DNS$_LOOKINGFOR set toDNS$K_SOFTLINK and request the attribute DNS$LINKTARGET. This can beuseful in discovering which link in a chain does not point to anexisting target. If the DECdns clerk detects a loop, it returnsDNS$_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 toits 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 specifieddirectory have absorbed all updates applied to any replica prior to thetime the skulk began. Successful update of the replica set requires allreplicas 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 attributevalue. This function returns DNS$_TRUE in the $DNS status block if thespecified 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 notexist, 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 returnsDNS$_TRUE in the $DNS status block if the specified member is a memberof the specified group (or a subgroup thereof), and DNS$_FALSEotherwise. If the clerk searches a subgroup and one or more of thesubgroups is unavailable, the clerk returns the status encountered intrying to access that group.

The DNS$_INOUTDIRECT argument, on input, controls the scope of thesearch. If you set this item code to 1, the clerk searches only thetop-level group. If you set it to 0, the clerk searches all of thesubgroups. On output, the clerk returns a 1 in theDNS$V_DNSB_INOUTDIRECT qualifying status if the member was found in thetop-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 orcontrol 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 anattribute. An attribute name cannot be longer than 31 characters.

DNS$_ATTRIBUTETYPE

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

DNS$_CLASS

The DNS$_CLASS item code specifies the DNS$Class attribute of an objectfor the $DNS function DNS$_CREATE_OBJECT. DNS$_CLASS is an opaquesimple name.

DNS$_CLASSFILTER

DNS$_CLASSFILTER specifies a filter that limits the scope of anenumeration to those objects belonging to a certain class or group ofclasses. DNS$_CLASSFILTER is used by the $DNS functionDNS$_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 areenumerated.

DNS$_CLEARINGHOUSE

DNS$_CLEARINGHOUSE specifies the clearinghouse in which the directorywill 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 aDECdns server to complete the request. DNS$_CONF is 1 byte longand 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 clerkassumes a value of DNS$K_LOW.

DNS$_CONTEXTVARNAME

DNS$_CONTEXTVARNAME specifies and returns a context for the enumerationfunctions. On input, specify null to set the initial context. Onoutput, DNS$_CONTEXTVARNAME returns the opaque simple name of the lastitem enumerated.

DNS$_CONTEXTVARNAME is optional. If you do not specify or you specify anull value for the context variable item, the clerk returns the resultsfrom the beginning of the set. To restart an enumeration where it leftoff, specify the last value returned in DNS$_CONTEXTVARNAME.

DNS$_CONTEXTVARTIME

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

DNS$_CONTEXTVARTIME is optional. If you do not specify or you specify anull value for the context variable item, the clerk returns the resultsfrom the beginning of the set. To restart a read operation where itleft 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 anopaque 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 willexpire. The clerk deletes the soft link at the expiration time. If thisitem code is a null value, the clerk neither checks nor deletes thelink.

DNS$_EXTENDTIME

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

DNS$_FROMFULLNAME

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

DNS$_FROMSIMPLENAME

DNS$_FROMSIMPLENAME specifies for the DNS$_SIMPLE_OPAQUE_TO_STRINGfunction the opaque simple name that is to be converted into stringformat.

DNS$_FROMSTRINGNAME

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

DNS$_GROUP

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

DNS$_INOUTDIRECT

DNS$_INOUTDIRECT specifies a value that controls the scope of a testfor 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 whichthe call is to operate. DNS$_LOOKINGFOR can take one of the followingvalues:

• 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 toindicate that the results of the read operation are to be cached. Thisis a single-byte item.

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

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

DNS$_MEMBER

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

DNS$_MODOPERATION

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

DNS$_MODVALUE

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

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

DNS$_NEXTCHAR_PTR

DNS$_NEXTCHAR_PTR is an optional item code that can be used with theparse functions DNS$_PARSE_FULLNAME_STRING andDNS$_PARSE_SIMPLENAME_STRING to return the address of an invalidcharacter that immediately follows a valid DECdns name. Thisoption is most useful when applications are parsing command linestrings.

Without this item code, the parse functions return an error if anyportion 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. Thisitem code is used with the DNS$_ENUMERATE_ATTRIBUTES functions. Theitem code returns either DNS$K_SET or DNS$K_SINGLE along with the setof attribute names.

The names returned in this set can be extracted from the buffer withthe DNS$REMOVE_FIRST_SET_VALUE routine. The resulting values arecontained in the $DNSATTRSPECDEF structure. This 1-byte structureindicates whether an attribute is set-valued or single-valued followedby an opaque simple name.

DNS$_OUTCHILDREN

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

You can extract the values resulting from the enumeration using theDNS$REMOVE_FIRST_SET_VALUE run-time library routine. These values arethe opaque simple names of the child directories found in the parentdirectory.

DNS$_OUTCTS

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

DNS$_OUTNAME

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

DNS$_OUTOBJECTS

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

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

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

DNS$_OUTSOFTLINKS

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

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

DNS$_OUTVALSET

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

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

DNS$_READCHSET

DNS$_READCHSET specifies the names of clearinghouses that containread-only replicas of the directory being reconstructed withDNS$_NEW_EPOCH.

DNS$_REPLICATYPE

DNS$_REPLICATYPE specifies the type of directory replica being added inthe 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 enumeratedwith the DNS$_ENUMERATE_OBJECTS function should be returned along withthe object names in the DNS$_OUTOBJECTS item code. The object's classis the value of the DNS$Class attribute.

DNS$_SECCHSET

DNS$_SECCHSET specifies the names of clearinghouses that containsecondary replicas of the directory being reconstructed withDNS$_NEW_EPOCH.

DNS$_SUPPRESS_NSNAME

DNS$_SUPPRESS_NSNAME specifies that the leading namespace name shouldnot be returned in the converted full name string. This item code isused by the DNS$_FULL_OPAQUE_TO_STRING function. This is an optionalsingle-byte value.

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

DNS$_TARGETNAME

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

DNS$_TOFULLNAME

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

DNS$_TOSIMPLENAME

DNS$_TOSIMPLENAME specifies for the DNS$_PARSE_SIMPLENAME_STRINGfunction the address of a buffer that will contain the resulting opaquesimple name.

DNS$_TOSTRINGNAME

DNS$_TOSTRINGNAME returns the string name resulting from one of theconversion functions: DNS$_FULL_OPAQUE_TO_STRING orDNS$_SIMPLE_OPAQUE_TO_STRING. DNS$_TOSTRINGNAME has the followingstructure:

[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 valuethat is to be tested. This item contains the address of a bufferholding the value.

DNS$_VERSION

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

DNS$_WAIT

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

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

DNS$_WILDCARD

DNS$_WILDCARD is an optional item code that specifies to theenumeration functions of $DNS the opaque simple name used to limit thescope of the enumeration. (The simple name does not have to use awildcard.) Only those simple names that match the wildcard are returnedby 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 anapplication (client) and DECdns. The DECdns clerkinterface is used to create, delete, modify, and retrieve DECdnsnames in a namespace.

A single system service call supports the DECdns clerk. It hastwo 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 servicesthat use a single item list for both input and output operations.

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

In addition to the system services, DECdns provides a set ofcallable run-time library routines. You can use the clerk run-timelibrary routines to manipulate output from the system service and towrite 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 NameService.

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

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

In all other respects, $DNSW is identical to $DNS. Refer to the $DNSdescription 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 thetransaction.

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 thisargument 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 flagsargument is a longword bit mask in which each bit corresponds to anoption flag. The $DDTMDEF macro defines symbolic names for these optionflags, described in Table SYS-27. All undefined bits must be 0. Ifthis 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 transactionis 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 inTable 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 inTable SYS-29. $END_BRANCH does not complete with this error until allbranches on the local node have been removed from the transaction. Thusthis call to $END_BRANCH cannot complete with the SS$_ABORT error untilafter every authorized and synchronized branch on the local node hasinitiated 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 thetransaction. $END_BRANCHW always waits for the request to completebefore 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 outcomeof 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. Ifthis 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 flagsargument is a longword bit mask in which each bit corresponds to anoption flag. The $DDTMDEF macro defines symbolic names for these optionflags, which are defined in Table SYS-30.

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

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 returnedcontains:

• 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 reasoncodes, 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 ofthe calling process.

Description

The End Transaction service ends a transaction by attempting to commitit, 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, anunintended set of operations can be committed. This can invalidateapplication data managed by the resource managers participating in thetransaction.

  
  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 inTable SYS-32. $END_TRANS will not complete successfully (that is, theevent flag will not be set, the AST routine will not be called, and theI/O status block will not be filled in) until after each authorized andsynchronized branch of the transaction has initiated a call to$END_BRANCH.

$END_TRANS will not complete successfully (that is, the event flag willnot be set, the AST routine will not be called, and the I/O statusblock 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 isin supervisor, executive, or kernel mode, or while the calling processis at AST level. Successful completion of $END_TRANS is notindefinitely 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 inTable SYS-33. $END_TRANS does not complete with the SS$_ABORT erroruntil all branches on the local node have been removed from thetransaction. Thus it does not complete with this error until after eachauthorized and synchronized branch on the local node has initiated acall to either $END_BRANCH or $ABORT_TRANS.

Note that the completion of $END_TRANS with the SS$_ABORT error is notindefinitely 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 outcomeof the transaction.

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

Do not call $END_TRANSW from asynchronous system trap (AST) level, orfrom an access mode that is more privileged than the DECdtm calls madeby 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 LockInformation) services together provide the user interface to the LockManagement facility. Refer to the descriptions of these other servicesfor additional information about lock management.

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

For additional information about system service completion, see theSynchronize ($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 intrsdm_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 orcanceled. Cancellation occurs if you use $DEQ with the cancel modifieror if the waiting request is chosen to break a deadlock. Theefn 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 eventflag 0 if efn was not specified). Then, when the lockrequest is granted, the specified event flag (or event flag 0) is setunless you specified the LCK$M_SYNCSTS flag in theflags argument.

lkmode

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

Lock mode requested. The lkmode argument is a longwordspecifying this lock mode.

Each lock mode has a symbolic name. The $LCKDEF macro defines thesesymbolic names. The following table gives the symbolic name anddescription 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 valueblock. The initial value of the lock value block is zero (0). When youspecify the LCK$M_VALBLK flag in the flags argument,the lock status block contains a lock value block. In this case, the16-byte lock value block appears at the beginning of the first bytefollowing the eighth byte of the lock status block, bringing the totallength of the lock status block to 24 bytes.

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

The following table defines the status block fields:

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

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

flags

The $LCKDEF macro defines a symbolic name for each flag bit. Thefollowing 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 argumentshould be specified because the default value for theresnam argument produces an error when it is used tocreate a lock. The resnam argument is ignored for lockconversions.

parid

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

astadr

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

astprm

blkast

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

acmode

This argument does not affect the access mode associated with the lockor its blocking and completion ASTs. The acmodeargument is a longword containing the access mode. The $PSLDEF macrodefines the following symbols for the four access modes:

The $ENQ service associates an access mode with the lock in thefollowing 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 conversionon a resource. The $ENQ service completes asynchronously; that is, itreturns to the caller after queuing the lock request without waitingfor the lock to be either granted or converted. For synchronouscompletion, 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 orconverted.

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

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

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

Invalidation of the Lock Value Block

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

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

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 musteither have SYSLCK privilege or be executing in executive or kernelmode.

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

To queue a lock conversion, the access mode associated with the lockbeing converted must be equal to, or less privileged than, the accessmode 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 grantedor converted. For asynchronous completion, use the Enqueue Lock Request($ENQ) service; $ENQ returns to the caller after queuing the lockrequest, without waiting for the lock to be either granted orconverted. 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 theSynchronize ($SYNCH) service documentation.

The $ENQ, $ENQW, $DEQ, and $GETLKI services together provide the userinterface 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 intrsdm_id,...);

The Enter service inserts a file name in a directory.

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

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. Thetype argument is a longword containing the type ofstorage.

The three storage types, together with their symbolic names, aredefined 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 eraseoperation. The count argument is a longword containingthe iteration count.

You should call the $ERAPAT service initially with thecount argument set to 1, the second time with thecount argument set to 2, and so on, until the statuscode 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 patadrargument is the address of a longword into which the security erasepattern is to be written.

Description

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

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

The following example demonstrates how to use the $ERAPAT service toperform 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 hasnot been returned, $QIO is called to write the pattern returned by$ERAPAT onto the disk. After this write, $ERAPAT is called again andthe cycle is repeated until the code SS$_NOTRAN is returned, at whichpoint 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 $ERAPATCHANNEL: .WORD 0 ; Channel assigned to disk deviceDEVICE: .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 $ERAPAT10$: $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 directoryentry specified in the path to the file. If additional directoryentries have been created for this file by the Enter service, you mustuse the Remove service to delete them.

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

Initiates image rundown when the current image in a process completesexecution. 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 completionstatus of the current image. If you do not specify this argument in amacro call, a value of 1 is passed as the completion code for VAX MACROand VAX BLISS--32, and a value of 0 is passed for other languages. Youcan test this value at the command level to provide conditional commandexecution.

Description

The $EXIT service is unlike all other system services in that it doesnot return status codes in R0 or anywhere else. The $EXIT service doesnot return control to the caller; it performs an exit to the commandinterpreter or causes the process to terminate if no commandinterpreter 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 programregion or control region for the execution of the current image.Expansion occurs at the current end of that region's virtual addressspace.

Format

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

C Prototype

int sys$expreg (unsigned int pagcnt, struct _va_range *retadr, unsignedint 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 addto the current end of the program or control region. Thepagcnt argument is a longword value containing thisnumber.

On Alpha systems, the specified value is rounded up to an even multipleof 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 $EXPREGhas actually added. The retadr argument is the addressof a 2-longword array containing, in order, the starting and endingprocess 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. Theacmode argument is a longword containing the accessmode.

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

The newly added pages are given the following protection: (1) read andwrite access for access modes equal to or more privileged than theaccess mode used in the call, and (2) no access for access modes lessprivileged 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. Theregion argument is a longword value. A value of 0 (thedefault) specifies that the program region (P0 region) is to beexpanded. A value of 1 specifies that the control region (P1 region) isto be expanded.

Description

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

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

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

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

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

Required Access or Privileges

None

Required Quota

The process's paging file quota (PGFLQUOTA) must be sufficient toaccommodate 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 theretadr argument (if specified) can be used as theinput 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 allocationpages to a process's virtual address space for the execution of thecurrent image. Expansion occurs at the next free available addresswithin 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 __int64length_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 inSTARLET.MLB define a symbolic name for each of the three defaultregions 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 bespecified.

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 specifiedmust 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 modedetermines the owner mode of the pages as well as the read and writeprotection on the pages. The acmode argument is alongword containing the access mode. The $PSLDEF macro defines symbolsfor the four access modes.

The $EXPREG_64 service uses whichever of the following two access modesis 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 modeassociated with it that is more privileged than the caller's mode. Thecondition value SS$_IVACMODE is returned if the caller is lessprivileged 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 pagescreated. The flags argument is a longword bit vectorin which each bit corresponds to a flag. The $VADEF macro and theVADEF.H file define a symbolic name for each flag. You construct theflags argument by performing a logical OR operation onthe symbol names for all desired flags.

All bits in the flags argument are reserved for futureuse by HP and should be specified as 0. The condition value SS$_IVVAFLGis 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 virtualaddress of a naturally aligned quadword into which the service returnsthe 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 intowhich the service returns the length in bytes of the virtual addressrange created.

Description

The Expand Virtual Address Space service is a kernel mode service thatcan be called from any mode. This service adds a range of demand-zeroallocation pages to a process's virtual address space for the executionof the current image. Expansion occurs at the next free availableaddress within the specified region. The new pages, which werepreviously inaccessible to the process, are created as demand-zeropages.

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

Successful return status from $EXPREG_64 Expand Virtual Address servicemeans that the specified region's virtual address space was expanded bythe number of bytes specified in the length_64argument.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments. If a condition value other than SS$_ACCVIO is returned, thereturned address and returned length indicate the pages that weresuccessfully 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 pointedto by the return_length_64 argument.

Required Privileges

None

Required Quota

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

The process's paging file quota (PGFLQUOTA) must be sufficient toaccommodate 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 diskfile. This service is most useful for extending relative files andindexed files when you are doing block I/O transfers using the Writeservice.

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

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

The Formatted ASCII Output with List Parameter ($FAOL) service providesan 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 outputtogether with one or more $FAO directives. $FAO directives are used tospecify repeat counts or the output field length, or both, and they arepreceded by an exclamation point (!). The ctrstrargument is the 32- or 64-bit address (on Alpha systems) or the 32-bitaddress (on VAX systems) of a character string descriptor pointing tothe control string. The formatting of the $FAO directives is describedin the Description section.

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

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

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

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

The $FAO service reads parameters from the argument list specified inthe call; these arguments have the names p1,p2, p3, and so on, up top17. 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 acceptsany 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 (onAlpha systems) or the 32-bit address (on VAX systems) of a wordcontaining 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 (onAlpha systems) or the 32-bit address (on VAX systems) of a characterstring descriptor pointing to the output buffer. The maximum number ofbytes 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 aquadword containing the parameter needed by the first $FAO directiveencountered in the control string, the p2 argument isa quadword containing the parameter needed for the second $FAOdirective, and so on for the remaining arguments up top17. If an $FAO directive does not require aparameter, that $FAO directive is processed without reading a parameterfrom 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 outputstring, or a length or argument count. Each directive in the controlstring 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. Theprmlst argument is the 32- or 64-bit address (on Alphasystems) or the 32-bit address (on VAX systems) of a list of longwordswherein each longword is a parameter. The $FAOL service processes theseparameters sequentially as it encounters, in the control string, $FAOdirectives that require parameters.

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

Description

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

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

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

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

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

$FAO Directives

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

!DD

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

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

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 byusing 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 theindirect directive @. This immediately precedes the directive (@DD),and indicates that the next parameter is the address of the valueinstead of the value itself. This directive must be used with anydirective that can produce a quadword output when using $FAOL;otherwise, $FAOL creates a 64-bit sign-extended value. This includesthe 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 thesystem, use the following conventions when using the $FAO and $FAOLsystem 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 fillcharacters.

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 withseveral directives, parameters defined as input for the directives, andthe calls to $FAO to format the output strings.

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

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

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 willcheck the returned status, and write the output string produced by $FAOif no error occurred. The following code fragment shows how the examplecall may be made, and the resultant string output to the user'sterminal.

#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 forOpenVMS 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 (shownas <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 tobe 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. $FAOleft-justifies each string into a field of eight characters (the outputfield length specified).

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

If the directive were specified without an output field length, thatis, if the directive were specified as !3(AS), the three output fieldswould 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 isconverted to hexadecimal, and the value --400 is converted to signeddecimal. The ASCII results of each conversion are placed in theappropriate position in the output string.

Note that the hexadecimal output string has eight characters and iszero-filled to the left. This is the default output length forhexadecimal 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, unlikethe $FAO directive, which requires each parameter on the call to bespecified, the $FAOL directive points to a list of consecutivelongwords, 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, thecontrol string (fao_desc) specifies that byte values are to beconverted. $FAO uses the low-order byte of each longword parameterpassed to it. The high-order three bytes are not evaluated. Comparethese 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 andoutput lengths. First, $FAO performs the !XW directive twice, using thelow-order word of the numeric parameters passed. The output lengthspecified is two characters longer than the default output field widthof hexadecimal word conversion, so two spaces are placed between theresulting ASCII strings.

The !-- directive causes $FAO to back up over the parameter list. Arepeat count is specified with the directive so that $FAO skips backover two parameters; then, it uses the same two parameters for the !ZWdirective. The !ZW directive causes the output string to be zero-filledto 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 adifferent parameter list; each list contains, in the first longword,the address of a character string descriptor. The second longwordbegins an argument list, with the number of arguments remaining in thelist. The control string uses this second longword twice: first tooutput the value contained in the longword, and then to provide therepeat 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 valueconverted has a value not equal to 1, $FAO outputs the characters; if the value is a 1 (as in Example B), $FAO does not outputthe character s. $FAO outputs the plural character inlowercase since the preceding character was in lowercase.

The output field length defines a width of four characters for eachbyte 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 thedirective, $FAO also writes a space after the greater-than characterson output.

The !%D directive requires the address of a quadword time value, whichmust be in the system time format; however, when the address of thetime value is specified as 0, $FAO uses the current date and time. Fora detailed description of the ASCII date and time string returned, seethe 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 sothat $FAO truncates the time from the date and time string, and outputsonly the date.

The !#*_ directive requests that the underscore character (_) berepeated the number of times specified by the next parameter. Becausep2 is specified as 5, five underscores are writteninto the output string.

The !%T directive normally returns the full system time. The !5%Tdirective provides an output length for the time; only the hours andminutes 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 thefield defined are two directives, !AC and !UL. The strings substitutedby these directives can vary in length, but the entire field always has25 characters.

The !7UL directive formats the longword passed in each example(p2 argument) and right-justifies the result in a7-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 usedto output the following string:

FILE [BOELITZ]TESTING.DAT ABORTED AT ERROR 25

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

$FAOL_64 interprets the parameter list as a list of quadwords ratherthan a list of longwords. In all other respects, $FAOL_64 is identicalto $FAOL. For all other information about the $FAOL_64 service, referto 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-bitstring 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 outputlength, 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 pointsto the output buffer into which $FAOL_64 writes the fully formattedoutput 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 FAOarguments.

Searches a string for a file specification and parses the components ofthat 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. Thesrcstr argument is the address of a descriptorpointing 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 tobe returned by $FILESCAN. The components are the full nodespecification, 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 addressof a list of item descriptors wherein each item descriptor specifiesone component. The list of item descriptors is terminated by a longwordof 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 flagbit. The following table shows the file specification component thatcorresponds to the symbolic name of each flag bit:

The fldflags argument is optional. When you want toknow which components of a file specification are present in a stringbut 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 theentire source string, with quotation information reduced and simplifiedfor only the primary node, into the auxiliary output buffer.

When the auxiliary output buffer is provided, all addresses returned inthe 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 devicename includes the single colon (:).

FSCN$_DIRECTORY

Returns the length and starting address of the directory name. Thedirectory 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 nameincludes no syntactical elements.

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

If there is no name component but there is either a type or versioncomponent, the flags argument for FSCN$V_NAME is set and the addressfield contains a nonzero pointer (pointing to the period for the typecomponent); 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 primarynode's access control string, any secondary node information, and thefinal double colon (::).

FSCN$_NODE_ACS

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

FSCN$_NODE_PRIMARY

Returns the length and starting address of the primary node name. Ifmultiple nodes are specified, the primary node name represents thefirst node specification. The node name does not include the doublecolon (::) or any access control information. If an auxiliary outputbuffer is specified, quotation information is reduced and simplifiedfor only the primary node.

FSCN$_NODE_SECONDARY

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

FSCN$_ROOT

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

FSCN$_TYPE

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

FSCN$_VERSION

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

Description

The Scan String for File Specification service searches a string for afile specification and parses the components of that filespecification. When $FILESCAN locates a partial file specification (forexample, DISK:[FOO]), it returns the length and starting address ofthose components that were requested in the item list and were found inthe string. If a component was requested in the item list but not foundin the string, $FILESCAN returns a length of 0 and an address of 0 tothe 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 componentsdescribes the entire contiguous file specification string. For example,to extract only the file name and file type from a full filespecification string, you can add the length of these two componentsand use the address of the first component (file name). However, thespecific node name and node control strings extracted using theFSCN$_NODE_PRIMARY and FSCN$_NODE_ACS item codes cannot be recombinedbecause the double colon (::) is not included in either string.

If an auxiliary output buffer is provided, $FILESCAN copies the entiresource string, removing and reducing quotation marks from the primarynode 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 nodespecifications. A node specification is a node name, followed by anoptional access control string, followed by a double colon (::). A nodename 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 nodeabc"def" would be represented as "abc""def""". An accesscontrol string is a quoted string containing a user name, an optionalpassword, and an optional account name. Note that the double quotes areonly used to differentiate between a primary node name containingembedded quotes and the access control string. See the Example sectionfor 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 assumesthat the space terminates the full file specification string.

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

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

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

The $FILESCAN service does not (1) assume default values forunspecified file specification components, (2) perform logical nametranslation 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."#endifchar *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_SCANEnter file name: abc"def"The file name is abc"def"The component NAME is present: abcEnter file name: "abc""def"""There is no file name returned for FSCN$_FILESPECEnter 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: abcThe component NODE_ACS is present: "def"Enter file name: "abc""def""""system password"::[dir.1]a^ ^".file;1The file name returned is abc"def""system password"::[dir.1]a^ ^".file;1The 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: .fileThe component VERSION is present: ;1The 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 itsrecord file address in the RAB$W_RFA field of the RAB. The Find servicecan be used with all file organizations.

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

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 completesexecution. The holder argument is the address of aquadword data structure containing the holder identifier. This quadworddata 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. Theid argument is the address of a longword containingthe 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 idwhen $FIND_HELD completes execution. The attribargument is the address of a longword containing a bit mask specifyingthe attributes.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The symbols are defined in the systemmacro library ($KGBDEF). The following are the symbols for each bitposition:

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. Thecontxt argument is the address of a longword usedwhile searching for all identifiers. The context value must beinitialized to 0, and the resulting context of each call to $FIND_HELDmust be presented to each subsequent call. Aftercontxt is passed to $FIND_HELD, you must not modifyits value.

Description

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

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

Note that, when you use wildcards with this service, the records arereturned in the order that they were originally written because thefirst record is located on the basis of the holder ID. Thus, all thetarget records have the same holder ID or, in other words, they haveduplicate keys, which leads to retrieval in the order in which theywere written.

Required Access or Privileges

Read access to the rights database is required to obtain informationabout 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 OpenVMSRMS, this service can also return RMS status codes associated withoperations 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. Theid argument is a longword containing the binaryidentifier value.

holder

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

Holder identifier returned when $FIND_HOLDER completes execution. Theholder argument is the address of a quadwordcontaining the holder identifier. The first longword contains the UICof the holder with the high-order word containing the group number andthe low-order word containing the member number. The second longwordcontains 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 byholder. The attrib argument is theaddress of a longword containing the attribute mask.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The symbols are defined in the systemmacro library ($KGBDEF). The following are the symbols for each bitposition:

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 specifiedidentifier when executing $FIND_HOLDER. The contxtargument is the address of a longword containing the context value.When calling $FIND_HOLDER repeatedly, contxt must beset initially to 0 and the resulting context of each call to$FIND_HOLDER must be presented to each subsequent call. After theargument is passed to $FIND_HOLDER, you must not modify its value.

Description

The Find Holder of Identifier service returns the holder of thespecified identifier. To determine all the holders of the specifiedidentifier, you call SYS$FIND_HOLDER repeatedly until it returns thestatus code SS$_NOSUCHID, which indicates that $FIND_HOLDER hasreturned all identifiers, cleared the context longword, and deallocatedthe record stream. If you complete your calls to $FIND_HOLDER beforeSS$_NOSUCHID is returned, you use the $FINISH_RDB service to clear thecontext value and deallocate the record stream.

Note that when you use wildcards with this service, the records arereturned in the order in which they were originally written. (Thisaction results from the fact that the first record is located on thebasis of the identifier. Thus, all the target records have the sameidentifier or, in other words, they have duplicate keys, which leads toretrieval in the order in which they were written.)

Required Access or Privileges

Read access to the rights database is required to obtain informationabout 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 OpenVMSRMS, this service can also return RMS status codes associated withoperations 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. Thecontxt argument is a longword containing the addressof the context value.

Description

The Terminate Rights Database Context service clears the contextlongword and deallocates the record stream associated with a sequenceof rights database lookups performed by the $IDTOASC, $FIND_HOLDER, and$FIND_HELD services.

If you repeatedly call $IDTOASC, $FIND_HOLDER, or $FIND_HELD untilSS$_NOSUCHID is returned, you do not need to call $FINISH_RDB becausethe record stream has already been deallocated and the context longwordhas 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 OpenVMSRMS, this service can also return RMS status codes associated withoperations 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 fileattributes associated with the file. This ensures that all recordactivity up to the point at which the Flush service executes isactually reflected in the file.

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

Causes an Exit ($EXIT) service call to be issued on behalf of aspecified 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. Thepidadr argument is the address of a longwordcontaining the PID.

The pidadr argument can refer to a process running onthe local node or a process running on another node in the OpenVMSCluster system.

The pidadr argument is optional but must be specifiedif the process that is to be forced to exit is not in the same UICgroup 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. Theprcnam argument is the address of a character stringdescriptor pointing to the process name string. A process running onthe local node can be identified with a 1- to 15-character string. Toidentify a process on a particular node in a cluster, specify the fullprocess 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 ofprocesses in the same UIC group as the calling process. To forceprocesses in other groups to exit, you must specify thepidadr argument. This restriction exists because theoperating system interprets the UIC group number of the calling processas part of the specified process name; the names of processes areunique 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. Thecode argument is a longword containing this value. Ifyou do not specify the code argument, the value 0 ispassed as the completion code.

Description

The Force Exit service causes an Exit service call to be issued onbehalf of a specified process.

If you specify neither the pidadr nor theprcnam argument, the caller is forced to exit andcontrol is not returned.

If the longword at address pidadr is 0, the PID of thetarget process is returned.

The Force Exit system service requires system dynamic memory.

The image executing in the target process follows normal exitprocedures. For example, if any exit handlers have been specified, theygain 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 asynchronoussystem trap (AST) is queued for the target process. The AST routinecauses the $EXIT service call to be issued by the target process.Because the AST mechanism is used, user mode ASTs must be enabled forthe target process, or no exit occurs until ASTs are reenabled. Thus,for example, a suspended process cannot be stopped by $FORCEX. Theprocess that calls $FORCEX receives no notification that the exit isnot being performed.

If an exit handler resumes normal processing, the process will notexit. In particular, if the program is written in Ada and there is atask within the program that will not terminate, the program will notexit.

The $FORCEX service completes successfully if a force exit request isalready in effect for the target process but the exit is not yetcompleted.

Required Access or Privileges

Depending on the operation, the calling process might need a certainprivilege 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.)