HP OpenVMS Systems Documentation

Performs initial setup for process preemption avoidance.

Format

SYS$SETUP_AVOID_PREEMPT enable

C Prototype

int sys$setup_avoid_preempt (int enable);

Arguments

enable

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

Enables or disables preemption avoidance. If theenable argument is set to 1, preemption avoidance isenabled; if 0, preemption avoidance is disabled.

Description

The Setup for Process Preemption Avoidance service is a kernel-modeinitialization routine that locks the necessary internal datastructures in memory so scheduling routines can access them abovepageable IPL. A process or thread can then set or clear the indicatorbit by calling the $AVOID_PREEMPT service.

In addition, if the process or thread has ALTPRI privilege,$SETUP_AVOID_PREEMPT sets a bit in the PKTA (a per-kernel-thread dataarea) to mark that the process or thread can prevent preemption byother processes or threads having the same base priority but not thosethat have a higher base priority.

Note that without ALTPRI, this service will still functionsuccessfully, but will only enable the $AVOID_PREEMPT service to avoidpreemptions due to quantum end.

Required Access or Privileges

None

Required Quota

None

Related Services

$AVOID_PREEMPT

Condition Values Returned

SS$_NORMAL

The service completed successfully.

Also, any values returned by the $LKWSET or $UNLKSET services.

Sets or clears the default transaction of the calling process.

Format

SYS$SET_DEFAULT_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm],[new_tid] ,[old_tid]]

C Prototype

int sys$set_default_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 the optionflag, described in Table SYS-53. All undefined bits must be 0. If thisargument is omitted, no flags are used.

Table SYS-53 $SET_DEFAULT_TRANS Option Flag

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.

iosb

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

The I/O status block in which the completion status of the service isreturned as a condition value. See the Condition Values Returnedsection.

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

astadr

astprm

new_tid

old_tid

A zero TID is returned if the calling process did not have a defaulttransaction prior to the call.

Description

The $SET_DEFAULT_TRANS system service:

• Sets or clears the default transaction of the calling process.
  If either the new_tid argument passes the null value or the new_tid argument is omitted or zero, then the default transaction of the calling process is cleared. Otherwise the default transaction of the calling process is set to the value passed in the new_tid argument.
• Returns the identifier (TID) of the previous default transaction of the calling process (the one that was set or cleared by this call to $SET_DEFAULT_TRANS), if the old_tid argument is not zero.

$SET_DEFAULT_TRANS may fail for various reasons, including a call to$START_TRANS or $START_BRANCH that changes the default transaction ofthe calling process in progress.

Following a successful completion of $SET_DEFAULT_TRANS:

• The calling process does not have a default transaction, if either the new_tid argument passed the null value or the new_tid argument was omitted or zero.
• The default transaction of the calling process is that passed in the new_tid argument, if that argument was specified and its value was not zero.
• The identifier (TID) of the previous default transaction of the calling process is returned in the old_tid argument, if that argument was not omitted.
  A null value is returned if the calling process did not previously have a default transaction.

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

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_BRANCH, $END_BRANCHW,$END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,$GET_DEFAULT_TRANS, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW,$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$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	The options flags were invalid.
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$_WRONGSTATE	The default transaction was being changed at the time of the call.

Sets or clears the default transaction of the calling process.

$SET_DEFAULT_TRANSW always waits for the request to complete beforereturning to the caller. Other than this, it is identical to$SET_DEFAULT_TRANS.

Format

SYS$SET_DEFAULT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm],[new_tid] ,[old_tid]]

C Prototype

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

Modifies the characteristics of a device or the paths used to accessthat device.

For synchronous completion, use the Set Device Characteristics and Wait($SET_DEVICEW) service. The $SET_DEVICEW service is identical to the$SET_DEVICE service, except that $SET_DEVICEW returns to the calleronly after the requested action has taken effect.

For additional information about system service completion, refer tothe Synchronize ($SYNCH) service.

Format

SYS$SET_DEVICE [efn] [,chan] [,devnam] ,itmlst [,iosb] [,astadr][,astprm] [,nullarg]

C Prototype

int sys$set_device (unsigned int efn, unsigned short int chan, void*devnam, void *itmlst, struct _iosb *iosb, void(*astadr)(__unknown_params), int astprm, struct_generic_64 *nullarg);

Arguments

efn

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

Number of the event flag to be set when $SET_DEVICE returns therequested information. The efn argument is a longwordcontaining this number; however, $SET_DEVICE uses only the low-orderbyte.

Upon request initiation, $SET_DEVICE clears the specified event flag(or event flag 0 if efn was not specified). Then, when$SET_DEVICE returns the requested information, it sets the specifiedevent flag (or event flag 0).

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 $SET_DEVICE, 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, $SET_DEVICE uses a default value of 0 forchan.

devnam

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

The name of the device about which $SET_DEVICE is to modify thecharacteristics or path settings. The devnam argumentis the address of a character string descriptor pointing to this namestring.

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 $SET_DEVICE, 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, $SET_DEVICE uses a default value of 0 forchan.

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.

Currently, $SET_DEVICE allows only one valid item listentry.

The following 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.

iosb

astadr

If you specify astadr, the AST routine executes at thesame access mode as the caller of the $SET_DEVICE service.

astprm

nullarg

Item Codes

SDV$_MP_SWITCH_PATH

Forces an immediate I/O path switch for the specified device. Theactive path will be switched from the current I/O path to the path namespecified in the buffer for this item code. Note that issuing$SET_DEVICE with SDV$_MP_SWITCH_PATH will initiate the process ofswitching the path. A delay may occur between when the servicecompletes and when the path switch is complete. A synchronous versionof this service, $SET_DEVICEW, is available that will wait until thepath switch attempt is complete before returning to the caller.

The path name specified in this and the following item codes must befully specified. It may be in either uppercase or lowercase, howeverthe entire name must be specified.

The Return Length field in this and the following item codes should setto zero.

The SDVDEF macro contains these item codes.

SDV$_MP_DISABLE_PATH

Disables the path specified in the buffer for this item code so that itwill no longer be considered as a switch candidate. Note that this doesnot apply to the current path, which cannot be disabled. The reasonsone might want to disable a path include the following:

• You know a specific path is broken or that a failover to that path will cause some members of the cluster to lose access.
• To prevent automatic switching to a selected path while it is being serviced.

SDV$_MP_ENABLE_PATH

Re-enables the path name specified in the buffer for this item code asa switch candidate.

Description

The Set Device service modifies the characteristics of devices or I/Opaths that have been established to those devices. For Multipath, theservice allows the user to switch the current I/O path to a differentavailable path and to enable and disable paths from being used for I/O.

Required Access or Privileges

None.

Required Quota

None.

Related Services

$ASSIGN, $DASSGN, $DEVICE_SCAN, $DEVICE_PATH_SCAN, $GETDVI, $GETDVIW

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$_EXQUOTA	Quota for pool has been exceeded.
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$_NOOPER	Caller does not have OPER privileges.
SS$_NOPRIV	The specified channel is not assigned or was assigned from a more privileged access mode.
SS$_NOSUCHDEV	The specified device does not exist on the host system.
SS$_NOSUCHPATH	The specified pathname does not exist on the host system.
SS$_PATHAMBIG	The specified pathname is ambiguous for this device.

Modifies the characteristics of a device or the paths used to accessthat device.

The $SET_DEVICEW completes synchronously; that is, it returns to thecaller only after the requested action has taken effect.

Format

SYS$SET_DEVICEW [efn] [,chan] [,devnam] ,itmlst [,iosb] [,astadr][,astprm] [,nullarg]

C Prototype

int sys$set_devicew (unsigned int efn, unsigned short int chan, void*devnam, void *itmlst, struct _iosb *iosb, void(*astadr)(__unknown_params), int astprm, struct_generic_64 *nullarg);

On Alpha systems, controls or retrieves the activation state for theimplicit affinity system capability of a specific kernel thread or ofthe global process default.

This service accepts 64-bit addresses.

Format

SYS$SET_IMPLICIT_AFFINITY [pidadr] [,prcnam] [,state] [,cpu_id][,prev_mask]

C Prototype

int sys$set_implicit_affinity (unsigned int *pidadr, void *prcnam,struct _generic_64 *state, int cpu_id, struct _generic_64 *prev_mask);

Arguments

pidadr

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

Process identification (PID) of a kernel thread whose implicit affinityis to be modified or returned. The pidadr argument isthe 32- or 64-bit address of a longword that contains the PID.

Process selection is made through a combination of thepidadr and prcnam arguments. Ifneither are specified or if both have a zero value, the serviceoperations are made to the user capability mask of the current kernelthread of the current calling process. The pidadrargument takes precedence over the prcnam argumentwhere both are supplied in the service call.

If the bit constant CAP$M_IMPLICIT_DEFAULT_ONLY is specified in thestate argument, then the implicit affinity stateportion of the default capability mask is modified or returned instead.

prcnam

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

Process name of the process whose implicit affinity capability state isto be modified or returned. The prcnam argument is the32- or 64-bit address of a character string descriptor pointing to theprocess name string. A process can be identified with a 1- to15-character string. The service operations are made to the usercapability mask of the initial thread of the specified process.

If pidadr and prcnam are bothspecified, then pidadr is modified or returned andprcnam is ignored. If neither argument is specified,then the context of the current kernel thread of the calling process ismodified or returned.

state

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

State options that can be selected for the affected thread's implicitaffinity. The state argument is a pointer to aquadword bit vector wherein a bit corresponds to a requested state forthe implicit affinity feature. Only the bits specified below are used;the remainder of the quadword bits are reserved.

Each option (bit) has a symbolic name, defined in the $CAPDEF macro.The state argument is constructed by performing alogical OR operation using the symbolic names of each desired option.

The following table describes the symbolic name of each option:

Symbolic Name	Description
CAP$M_IMPLICIT_DEFAULT_ONLY	Indicates the specified operations are to be performed on the global cell instead of on a specific kernel thread. This bit supersedes any individual kernel thread specified in pidadr or prcnam. Specifying this bit constant applies the implicit affinity operations to all newly created processes.
CAP$M_IMPLICIT_AFFINITY_SET	Indicates that the implicit affinity capability bit is to be set for the specified kernel thread. This is mutually exclusive with CAP$M_IMPLICIT_AFFINITY_CLEAR.
CAP$M_IMPLICIT_AFFINITY_CLEAR	Indicates that the implicit affinity capability bit is to be cleared for the specified kernel thread. This is mutually exclusive with CAP$M_IMPLICIT_AFFINITY_SET.

cpu_id

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

Identifier of the CPU requested as the first CPU on which this kernelthread is to execute. The cpu_id is a longwordcontaining this number, which is in the supported range of individualCPUs from 0 to SYI$_MAX_CPUS - 1 .

If no explicit CPU is needed, specifying a value of -1 in this argumentindicates the system is to select the initial association based onsystem dynamics and load balancing.

Note that, regardless of what explicit CPU is supplied to thisargument, it will be taken only as a suggestion. This service willattempt to make the requested association, but it will be superseded byanother CPU if the system dynamics are adversely affected by theoperation.

prev_mask

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

Previous implicit affinity state mask for the specified kernel threadbefore execution of this call to $SET_IMPLICIT_AFFINITY. Theprev_mask argument is the 32- or 64-bit address of aquadword into which $SET_IMPLICIT_AFFINITY writes a bit mask specifyingthe implicit affinity state.

The current state of the kernel thread's current implicit affinityfeature can be determined by testing the returned mask with thesymbolic bit definitions described for the stateargument. These bit definitions are found in the $CAPDEF macro.

Description

The Modify Process Implicit Affinity system service modifies or returnsthe implicit affinity state for the specified kernel thread or from thesystem default process creation cell.

Setting a kernel thread's implicit affinity function indicates to thesystem that it is to schedule the process in ways that will maximizethe cache and TB performance in the current symmetric multiprocessing(SMP) configuration. This might tend to bias the process towardsspecific CPUs more than the standard scheduling algorithm wouldnormally have allowed.

Required Access or Privileges

The caller must have the ALTPRI privilege to callSYS$SET_IMPLICIT_AFFINITY to modify its own implicit affinitycapability bit. To modify another process' capability mask, the callermust have:

ALTPRI---To modify any process with a matching UIC
ALTPRI and GROUP---To modify any process in the same UIC group
ALTPRI and WORLD---To modify any process

To call SYS$SET_IMPLICIT_AFFINITY simply to retrieve the state of aspecific process or global bit, the caller need only have the followingprivileges:

None---To retrieve the state of itself or any process with a matching UIC
GROUP---To retrieve the state of any process in the same UIC group
WORLD---To retrieve the state of any process

Related Services

$CPU_CAPABILITIES, $PROCESS_CAPABILITIES, $PROCESS_AFFINITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	One or more arguments has an invalid value.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_NOSUCHTHREAD	The specified kernel thread does not exist.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.
SS$_IVLOGNAM	The process name string has a length of 0 or more than 15 characters.
SS$_NOPRIV	Insufficient privilege for attempted operation.
SS$_CPUCAP	No CPU can run the specified process with new capabilities.
SS$_INSFARG	Fewer than the required number of arguments were specified or no operation was specified.

Sets a simple value associated with a process.

Format

SYS$SET_PROCESS_PROPERTIESW mbz1 ,mbz2 ,mbz3 ,property ,value,prev_value

C Prototype

int sys$set_process_propertiesw (unsigned int mbz1, unsigned int mbz2,unsigned int mbz3, unsigned int property, unsigned __int64 value,unsigned __int64 *prev_value);

Arguments

mbz1,mbz2,mbz3

type:
access:

Reserved for future use by HP. Must be specified as 0.

property

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

A constant that selects which property to set.

Valid values for property are defined by the $PPROPDEF macro as follows:

Property Code	Description
PPROP$C_CASE_LOOKUP_TEMP	The type of case lookup to use. This value is set for the life of the currently active image. This value reverts to the permanent case setting on image rundown. In the absence of an explicit case lookup specification in a user-provided NAML, RMS uses this value to determine the case setting for the current file operation. Valid values are PPROP$K_CASE_BLIND and PPROP$K_CASE_SENSITIVE. Refer to the Guide to OpenVMS File Applications for additional information.
PPROP$C_CASE_LOOKUP_PERM	The type of case lookup to use. This value is set for the life of the process or until the case is set again. This value is copied to the PPROP$C_CASE_LOOKUP_TEMP setting at image rundown. Setting this value affects only future activated images for this process. To change the case setting for the current active image, you must modify the PPROP$C_CASE_LOOKUP_TEMP setting. Valid values are PPROP$K_CASE_BLIND and PPROP$K_CASE_SENSITIVE. Refer to the Guide to OpenVMS File Applications for additional information.
PPROP$C_HOME_RAD	The Resource Affinity Domain (RAD) to which the process is assigned. Newly mapped memory in the process will come from the home RAD of the process. Currently mapped memory will not move into the new home RAD unless $PURGWS is issued. Valid values are integers between 0 and the maximum RAD on the system. Valid home RADs must also contain either memory or CPUs. Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.
PPROP$C_PARSE_STYLE_TEMP	The type of command parsing to use. This value is set only for the life of the image. The value reverts to the permanent style on image rundown. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.
PPROP$C_PARSE_STYLE_PERM	The type of command parsing to use. This value is set for the life of the process unless the style is set again. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.

value

OpenVMS usage:	integer
type:	quadword (unsigned)
access:	read
mechanism:	by value

A quadword value to which to set the property.

prev_value

OpenVMS usage:	access_mode
type:	quadword (unsigned) address of a quadword value
access:	write
mechanism:	by reference

The address of a quadword that will receive the previous value of theproperty.

Description

The $SET_PROCESS_PROPERTIESW system service sets a simple valueassociated with a process.

This service is used for changing process properties that have amaximum of a single quadword. You can only change one property value ata time per call to this service.

Required Access or Privileges

None.

Required Quota

None.

Related Services

$GETJPI

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	Access violation.

Controls the association between a calling process and resource domains.

Format

SYS$SET_RESOURCE_DOMAIN func ,rsdm_id ,domain_number ,[nullarg],[access] ,[acmode]

C Prototype

int sys$set_resource_domain (unsigned int func, unsigned int *rsdm_id,unsigned int domain_number, unsigned int nullarg, unsigned int access,unsigned int acmode);

Arguments

func

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

Function code specifying the action that $SET_RESOURCE_DOMAIN is toperform. The func argument is a longword containingthis function code. See the Function Codes section for a description of$SET_RESOURCE_DOMAIN function codes.

rsdm_id

OpenVMS usage:	longword
type:	longword (unsigned)
access:	write only to join, read only to leave
mechanism:	by reference

Resource domain identification. The rsdm_id argumentis the address of a longword specifying the association of the callingprocess with the resource domain.

The RSDM$_JOIN_DOMAIN function returns a resource domainidentification. The RSDM$_LEAVE function requires thersdm_id argument as input to specify which resourcedomain association the process is leaving.

The resource domain identification can be used as input to the $ENQ and$ENQW system services.

domain_number

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

Domain number that identifies the resource domain. Thedomain_number argument is a longword value containingthe resource domain number.

The domain_number argument is required for theRSDM$_JOIN_DOMAIN function but ignored for the RSDM$_LEAVE function.

nullarg

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

Placeholder reserved to HP. You must specify 0.

access

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

Types of access desired when using the lock management services withinthe resource domain. The access argument is a longwordbit mask specifying the access types required; these can include read,write, and lock.

The following table lists the symbols that the $RSDMDEF macro defines,their descriptions, and the lock management system services that mightrequire each type of access:

Symbol	Access Description	System Service
RSDM$M_READ	Read lock value blocks	$DEQ, $ENQ, $ENQW, $GETLKI, $GETLKIW
RSDM$M_WRITE	Write lock value blocks	$DEQ, $ENQ, $ENQW,
RSDM$M_LOCK	Take locks	$ENQ, $ENQW

The service grants the desired access, provided your process has thenecessary access rights to the resource domain. If you do not specifythe access argument or if you specify 0,$SET_RESOURCE_DOMAIN attempts to access the domain in the followingorder:

1. Read, write, lock
2. Read, lock
3. Write, lock
4. Lock

The access attempt terminates with the first success.

The access argument defaults to 0. It is ignored forthe RSDM$_LEAVE function.

acmode

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

Access mode requested for the association to the resource domain. Themost privileged access mode granted is the access mode of the caller.Locks cannot be taken from access modes less privileged than the accessmode of the association.

The acmode argument is a longword containing theaccess mode. The $PSLDEF macro defines the following symbols for theaccess modes:

Symbolic Name	Access Mode	Privilege Rank
PSL$C_KERNEL	Kernel	High
PSL$C_EXEC	Executive	--
PSL$C_SUPER	Supervisor	--
PSL$C_USER	User	Low

The acmode argument is optional for theRSDM$_JOIN_DOMAIN function. If you do not specify theacmode argument, the access mode is set to the accessmode of the calling process. The acmode argument isignored for the RSDM$_LEAVE function.

Function Codes

RSDM$_JOIN_DOMAIN

A process has the option of forming multiple associations with one ormore resource domains. Each association can have different accessrights to the resource domain, such as to read lock value blocks or towrite lock value blocks. This request sets up a new association with aresource domain.

$SET_RESOURCE_DOMAIN verifies the desired access against the securityprofile of the resource domain. If the desired access is allowed, a newassociation to the resource domain is created, and a resource domainidentification for the association is returned.

This function code returns the following condition values:

SS$_NORMAL
SS$_BADPARAM
SS$_EXQUOTA
SS$_INSFMEM
SS$_NOOBJSRV
SS$_NOPRIV

RSDM$_LEAVE

This operation requests that a process end an association with aresource domain.

A process must leave a resource domain association in the same mode as,or in a more privileged mode than, the mode in which it joined theresource domain.

Before a process can end its association with a resource domain, itmust release all locks taken using that association.

This function code returns the following condition values:

SS$_NORMAL
SS$_BADPARAM
SS$_IVMODE
SS$_RSDM_ACTIVE
SS$_RSDMNOTFOU

Description

The Set Resource Domain system service enables a process to use thelock management system services $DEQ, $ENQ, $ENQW, $GETLKI, and$GETLKIW.

The lock management services enable processes with the appropriateaccess rights to take and release locks on resource names and toperform other functions related to lock management. Applications useresource names to represent resources to which they want to synchronizeaccess. A resource domain is a namespace for resource names. A processmust join a resource domain to take and release locks and to read andwrite value blocks associated with resources in that resource domain.

When a process requests to join a resource domain, $SET_RESOURCE_DOMAINperforms an access check. After $SET_RESOURCE_DOMAIN verifies thedesired access to the resource domain, the service creates anassociation between the resource domain and the calling process. Theassociation is represented by a resource domain identification. Aprocess can request different types of access to the same resourcedomain; the type of access is a characteristic of the association withthe resource domain.

Each time a process joins a resource domain, a new association iscreated.

Processes use their resource domain identifications when using $ENQ or$ENQW to request a new lock.

The service can grant the following three types of access to resourcedomains:

• The right to read lock value blocks
• The right to write lock value blocks
• The right to take and release locks

Required Access or Privileges

None

Required Quota

$SET_RESOURCE_DOMAIN uses system dynamic memory, which uses BYTLMquota, for the creation of the resource domain data structures.

Related Services

$DEQ, $ENQ, $ENQW, $GETLKI, $GETLKIW

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	The func, the domain_number, or the rsdm_id argument was specified incorrectly.
SS$_EXQUOTA	The caller has insufficient BYTLM quota.
SS$_INSFMEM	There is insufficient memory to join the resource domain.
SS$_IVMODE	An attempt was made to leave an association created by a more privileged access mode.
SS$_NOOBJSRV	The audit server process, which maintains the security profile for resource domains, is not running. The process access rights to the domain cannot be determined, so access is denied.
SS$_NOPRIV	Access to the resource domain was denied.
SS$_RSDM_ACTIVE	Unable to leave the resource domain because there are locks still associated with this resource domain.
SS$_RSDMNOTFOU	The resource domain was not found.

On Alpha and I64 systems, sets the return values in the Mechanism Array

Format

SYS$SET_RETURN_VALUE mechanism_arg, return_type, return_value

C Prototype

int sys$set_return_value (void *mechanism_arg, unsigned_int*return_type, void *return_value);

Arguments

mechanism_arg

OpenVMS usage:	mechanism vector address
type:	quadword (unsigned)
access:	read only
mechanism:	by value

The address of the location of the mechanism vector. If themechanism_arg argument is 0, the mechanism vector forthe currently active signal is used.

If the address of the return_type argument is 0, thereturn_value argument is fetched by value and istreated as return-type PSIG$K_FR_U32. This combination of arguments canbe used to set a condition code, such as SS$_ACCVIO, as a return value.

return_type

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

The address of the location of a longword that contains one of thefunction return signature codes.

If the address of the return_type argument is 0, thereturn_value argument is fetched by value and istreated as return-type PSIG$K_FR_U32. This combination of arguments canbe used to set a condition code, such as SS$_ACCVIO, as a return value.

return_value

OpenVMS usage:	buffer
type:	scalar
access:	read only
mechanism:	by reference

The address of the location that contains a value of the appropriatetype. The referenced value is read as a longword, quadword, oroctaword, depending on the return_type.

If the address of the return_type argument is 0, thereturn_value argument is fetched by value and istreated as return-type PSIG$K_FR_U32. This combination of arguments canbe used to set a condition code, such as SS$_ACCVIO, as a return value.

Description

The Set Return Value service allows the caller to specify the values inthe Mechanism Array. It can also be used to set a condition code.

Required Access or Privileges

None

Required Quota

None

Related Services

None

Condition Values Returned

status	Success or failure. The given return value is placed in the appropriate fields of the specified mechanism vector, according to the return type.
SS$_NORMAL	The service completed successfully.
SS$_BADPARAM
SS$_NOSIGNAL	No signal is currently active for an exception condition.

Modifies the security characteristics of a protected object.

Format

SYS$SET_SECURITY [clsnam] ,[objnam] ,[objhan] ,[flags] ,[itmlst],[contxt] ,[acmode]

C Prototype

int sys$set_security (void *clsnam, void *objnam, unsigned int *objhan,unsigned int flags, void *itmlst, unsigned int *contxt, unsigned int*acmode);

Arguments

clsnam

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

Name of the object class. The clsnam argument is theaddress of a descriptor pointing to a string that contains the name ofthe object class.

The following is a list of the protected object class names:

CAPABILITY
COMMON_EVENT_CLUSTER
DEVICE
FILE
GLXGRP_GLOBAL_SECTION
GLXSYS_GLOBAL_SECTION
GROUP_GLOBAL_SECTION
ICC_ASSOCIATION
LOGICAL_NAME_TABLE
QUEUE
RESOURCE_DOMAIN
SECURITY_CLASS
SYSTEM_GLOBAL_SECTION
VOLUME

objnam

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

Name of the protected object whose associated security profile is goingto be retrieved. The objnam argument is the address ofa descriptor pointing to a string containing the name of the protectedobject.

The format of an object name is class specific. The following tablelists object names and describes their formats:

Object Class	Object Name Format
CAPABILITY	A character string. Currently, the only capability object is VECTOR.
COMMON_EVENT_CLUSTER	Name of the event flag cluster, as defined in the Associate Common Event Flag Cluster ($ASCEFC) system service.
DEVICE	Standard device specification, described in the OpenVMS User's Manual.
FILE	Standard file specification, described in the OpenVMS User's Manual.
GROUP_GLOBAL_SECTION	Section name, as defined in the Create and Map Section ($CRMPSC) system service.
ICC_ASSOCIATION	ICC security object name node::association_name. The special node name, ICC$::, refers to entries in the clusterwide registry. For registry entries, the Access Access Type does not apply.
LOGICAL_NAME_TABLE	Table name, as defined in the Create Logical Name Table ($CRELNT) system service.
QUEUE	Standard queue name, as described in the Send to Job Controller ($SNDJBC) system service.
RESOURCE_DOMAIN	An identifier or octal string enclosed in brackets.
SECURITY_CLASS	Any class name shown in the Object Class column of this table, or a class name followed by a period (.) and the template name. Use the DCL command SHOW SECURITY to display possible template names.
SYSTEM_GLOBAL_SECTION	Section name, as defined in the Create and Map Section ($CRMPSC) system service.
VOLUME	Volume name or name of the device on which the volume is mounted.

objhan

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

Data structure identifying the object to address. Theobjhan argument is an address of a longword containingthe object handle. You can use the objhan argument asan alternative to the objnam argument; for example, achannel number clearly specifies the file open on the channel and canserve as an object handle.

The following table shows the format of the object classes:

Object Class	Object Handle Format
COMMON_EVENT_CLUSTER	Event flag number
DEVICE	Channel number
FILE	Channel number
RESOURCE_DOMAIN	Resource domain identifier
VOLUME	Channel number

flags

OpenVMS usage:	flags
type:	mask_longword
access:	read only
mechanism:	by value

Mask specifying processing options. The flags argumentis a longword bit vector wherein a bit, when set, specifies thecorresponding option. The flags argument requires thecontxt argument.

The following table describes each flag:

Symbolic Name	Description
OSS$M_LOCAL	Do not update the master profile for the specified object. This flag allows you to call $SET_SECURITY several times to modify a local copy of a profile; once the modifications are satisfactory, you can clear the OSS$M_LOCAL flag, set the OSS$M_RELCTX flag, and have $SET_SECURITY update the master profile. The flag applies only to calls made with the contxt argument.
OSS$M_RELCTX	Release the context structure at the completion of this request.

The $OSSDEF macro defines symbolic names for the flag bits. Youconstruct the flags argument by specifying thesymbolic names of each desired option.

itmlst

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

Item list specifying which information about the process or processesis to be modified. The itmlst argument is the addressof a list of item descriptors, each of which describes an item ofinformation. The list of item descriptors is terminated by a longwordof 0.

With the item list, the user modifies the protected object'scharacteristics. The user defines which security characteristics tomodify. If this argument is not present, only theflags argument is processed. Without theitmlst argument, you can only manipulate thesecurity profile locks or release contxt resources.

The following data structure depicts the format of a single itemdescriptor:

The following table defines the item descriptor fields:

contxt

Because an active context block consumes process memory, be sure torelease the context block by setting the RELCTX flag when the profileprocessing is complete. $SET_SECURITY sets the context argument to 0once the context is released.

acmode

HP recommends that this argument be omitted (passed as zero).Item Codes The following table provides a summary of item codes thatare valid as an item descriptor in the itmlstargument. The table lists the $SET_SECURITY item codes and gives acorresponding description. Complete descriptions of each item code areprovided after the table.

OSS$_ACL_ADD_ENTRY

Adds an access control entry (ACE) pointed to by the buffer address sothat it is in front of the current ACE in the access control list(ACL). See OSS$_ACL_POSITION for more information on explicit accesscontrol list positioning.

OSS$_ACL_DELETE

Deletes all unprotected ACEs in an ACL.

OSS$_ACL_DELETE_ALL

Deletes an entire ACL, including protected ACEs.

OSS$_ACL_DELETE_ENTRY

Deletes an ACE pointed to by the buffer address or, if the bufferaddress is specified as 0, the ACE at the current position.

OSS$_ACL_FIND_ENTRY

Locates an ACE pointed to by the buffer address. OSS$_ACL_FIND_ENTRYsets the position within the ACL for succeeding ACL operations; forexample, for a deletion or modification of the ACE. If the bufferaddress is 0, it returns SS$_ACCVIO.

OSS$_ACL_FIND_NEXT

Advances the current position to the next ACE in the ACL.

OSS$_ACL_FIND_TYPE

Returns an ACE of a particular type if there is one in the bufferpointed to by the buffer address. OSS$_ACL_FIND_TYPE sets the positionwithin the ACL for succeeding ACL operations. If the buffer address is0, it returns SS$_ACCVIO.

OSS$_ACL_MODIFY_ENTRY

Replaces an ACE at the current position with the ACE pointed to by thebuffer address.

OSS$_ACL_POSITION_BOTTOM

Sets the ACL position to point to the bottom of the ACL.

OSS$_ACL_POSITION_TOP

Sets the ACL position to point to the top of the ACL.

OSS$_OWNER

Sets the owner UIC of the selected object to the value in the buffer.The buffer size must be 4 bytes.

OSS$_PROTECTION

Sets the selected object's protection code to the value in the buffer.The buffer size must be 2 bytes.

Description

The Set Security service modifies the security characteristics of aprotected object. Security characteristics include such information asthe protection code, the owner, and the access control list (ACL).

The security management services, $SET_SECURITY and $GET_SECURITY,maintain a single master copy of a profile for every protected objectin an OpenVMS Cluster system. They also ensure that only one process ata time can modify an object's security profile.

When you call $SET_SECURITY, the service performs the following steps:

1. It selects the specified protected object.
2. It fetches a local copy of the object's security profile, unless the service is operating on an existing context.
3. It modifies the local profile.
4. It updates the master copy of the profile if the local flag is clear and there was no error.
5. It deletes the local copy of the profile and returns if RELCTX is specified or if no context is specified.

There are different ways of identifying which protected object$SET_SECURITY should process:

• Whenever the contxt argument has a nonzero value, $SET_SECURITY uses the context to select the object and ignores the class name, object name, and object handle.
• With some types of objects, such as a file or a device, it is possible to select an object on the basis of its objhan and clsnam values.
• When the clsnam and objnam arguments are provided, $SET_SECURITY uses an object's class name and object name to select the object.

The context for a security management operation can be establishedthrough either $GET_SECURITY or $SET_SECURITY. Whenever the context isset by one service, the other service can use it provided the necessarylocks are being held. A caller to $GET_SECURITY needs to set the writelock flag (OSS$M_WLOCK) to inspect a profile value, maintain the lockon the object's profile, and then modify some value through a call to$SET_SECURITY.

There are many situations in which the contxt argumentis essential. By establishing a context for an ACL operation, forexample, a caller can retain an ACL position across calls to$GET_SECURITY so that a set of ACEs can be read and modifiedsequentially. A security context is released by a call to $SET_SECURITYor $GET_SECURITY that sets the OSS$M_RELCTX flag. Once the context isdeleted, the user-supplied context longword is reset to 0.

Required Access or Privileges

Control access to the object is required.

Required Quota

None

Related Services

$GET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The parameter cannot be read and the buffer cannot be written.
SS$_BADPARAM	You specified an invalid object, attribute code, or item size.
SS$_INSFARG	The clsnam and objnam arguments are not specified, the clsnam and objhan arguments are not specified, or the contxt argument is not specified.
SS$_INVBUFLEN	The buffer size for one of the item codes was invalid.
SS$_INVCLSITM	The item code that you specified is not supported for the class.
SS$_INVFILFOROP	An invalid file name was specified; the file name contained either a node or wildcard specification.
SS$_MMATORB	The attempted update cannot be performed. The object profile was changed by another process.
SS$_NOCLASS	The named object class does not exist.
SS$_OBJLOCKED	The selected object is currently write locked.

Establishes a request for notification when an OpenVMS system eventoccurs.

Format

SYS$SET_SYSTEM_EVENT event ,astadr ,astprm ,acmode ,flags ,handle

C Prototype

int sys$set_system_event (unsigned int event, void(*astadr)(__unknown_params), int astprm, unsigned int acmode, unsignedint flags, struct _generic_64 * handle);

Arguments

event

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

Event code indicating the type of system event for which an AST is tobe delivered. The event argument is a value indicatingwhich type of event is of interest.

Each event type has a symbolic name. The $SYSEVTDEF macro defines thefollowing symbolic names:

Symbolic Name	Description
SYSEVT$C_ADD_MEMBER	One or more OpenVMS instances have joined the OpenVMS Galaxy sharing community.
SYSEVT$C_DEL_MEMBER	One or more OpenVMS instances have left the OpenVMS Galaxy sharing community.
SYSEVT$C_ADD_ACTIVE_CPU	One or more processors have become active within this OpenVMS instance.
SYSEVT$C_DEL_ ACTIVE_CPU	One or more processors have become inactive within this OpenVMS instance.
SYSEVT$C_ADD_CONFIG_CPU	One or more CPUs have been added to the set of available CPUs for this OpenVMS instance.
SYSEVT$C_DEL_CONFIG_CPU	One or more processors have been removed from this OpenVMS instance.
SYSEVT$C_TDF_CHANGE	The system's time differential factor has changed.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit reference

Notification AST routine to receive control after a change in OpenVMSsystem configuration occurs.

astprm

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

The quadword AST parameter to be passed to the AST routine.

acmode

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

Access mode at which the system event AST is to execute. Theacmode argument is a longword containing the accessmode.

Each access mode has a symbolic name. The $PSLDEF macro defines thefollowing symbols for the four access modes.

Symbolic Name	Description
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

The value of the access mode is maximized with the access mode of thecaller.

flags

type:
access:

Defined in SYSEVTDEF.

SYSEVT$M_REPEAT_NOTIFY

When this flag is set, event notification is repeated.

handle

OpenVMS usage:	handle
type:	quadword (unsigned)
access:	read/write
mechanism:	by reference

The virtual address of a naturally aligned quadword for the eventhandle.

Description

The Set System Event service establishes a request for notificationwhen a system event occurs. It may create a new system eventnotification object, add an event to a new or existing object, andenable notification on a new or existing object.

If the handle specified is zero, a new systemnotification request object is created, and a handle for the new objectis returned.

If the event specified is non-zero, that event isadded to the set of events which trigger notification on thenotification object.

The service will verify that the input parameters specify a validrequest and enable the object for notification. Notification isaccomplished by AST delivery. After the AST has been delivered,notification must again be enable on the object before anothernotification (AST delivery) can occur if flag is notset.

Errors are returned in the following cases:

• If quotas are exceeded, an error is returned. It is important to note that this routine returns an error and will not retry an attempt to get quota if quota is exhausted on the first attempt.
• See the Condition Values Returned section for types of errors that can be returned.
• If the astadr argument is omitted, and a new notification object is being created, SS$_BADPARAM is returned.
• If the event argument is incorrectly specified, SS$_BADPARAM is returned.
• If the access mode parameter is more privileged than the mode of the caller, the mode of the caller is used.
• If specified, the handle argument must be writeable from the mode of the caller. SS$_ACCVIO is returned if this is not the case.

Required Access or Privileges

None

Required Quota

ASTLM

Related Services

$CLEAR_SYSTEM_EVENT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_BADPARAM	One of more arguments has an invalid value.
SS$_EXASTLM	The process exceeded its quota for outstanding ASTs.
SS$_INSFMEM	The system dynamic memory is insufficient to complete the service.

Searches for and returns information about records in the intrusiondatabase matching the caller's specifications.

Format

SYS$SHOW_INTRUSION user_criteria ,intruder ,intruder_len ,breakin_block,[flags] ,[context]

C Prototype

int sys$show_intrusion (void *user_criteria, void *intruder, unsignedshort int *intruder_len, void *breakin_block, unsigned int flags,unsigned int *context);

Arguments

user_criteria

OpenVMS usage:	char_string or item_list_3
type:	character-coded text string or longword (unsigned)
access:	read only
mechanism:	by descriptor--fixed-length string descriptor or by reference

If the CIA$M_ITEMLIST flag is FALSE:

The user_criteria argument is the description ofintruder or suspect. The user_criteria argument is theaddress of a character-string descriptor pointing to a buffercontaining the user criteria to match an intrusion record's userspecification in the intrusion database.

The user_criteria argument is a character string ofbetween 1 and 1058 bytes containing characters to match the userspecification on records in the intrusion database.

A user specification is any combination of the suspect's or intruder'ssource node name, source user name, source DECnet for OpenVMS address,local failed user name, local terminal, or the string UNKNOWN. The userspecification for an intrusion record is based on the input to the$SCAN_INTRUSION service and the settings of the LGI system parameter.For more information, refer to the HP OpenVMS Guide to System Security.

Wildcards are allowed for the user_criteria argument.For more information about using wildcards to scan the intrusiondatabase, see the Description section.

If the CIA$M_ITEMLIST flag is TRUE:

The user_criteria argument is now the address of an32-bit item list. If the item list is used, one item, theCIA$_USER_CRITERIAL item, must be present in the item list.

The following table lists the valid item descriptions for theuser_criteria argument:

Item	Description
CIA$_OUTPUT_LIST	Address of an 8192-byte buffer into which the service writes the associated node information for the returned intrusion record.
CIA$_SCSNODE_LIST	Address of a list of 8-character null-padded SCS nodenames for which the caller wants to see intrusion information about.
CIA$_USER_CRITERIAL	Address of a buffer, 1-1058 bytes long, containing the intruder or suspect.

If a CIA$_SCSNODE_LIST item is provided, an intrusion record will onlybe returned if it originated on one of the nodes specified. If aCIA$_SCSNODE_LIST item is not provided, records from all nodes will becandidates for display. Multiple CIA$_SCSNODE_LIST items are permittedin the item list.

If a CIA$_OUTPUT_LIST item is provided, the item is filled withnode-count records on return. The returned intrusion record will have abreakin block with a valid attempt-count field. The node-count recordswill have the name and attempt-count for each node represented.

intruder

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

User specification of the matched intruder or suspect record in theintrusion database. The intruder argument is theaddress of a character-string descriptor pointing to a buffer toreceive the user specification of the matched record in the intrusiondatabase.

The intruder argument is a 1058-byte string that willreceive the user specification of a record in the intrusion databasethat matches the specifications in the user_criteriaand flags arguments.

intruder_len

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

Length of returned string in the intrusion buffer. Theintruder_len argument is the address of a longword toreceive the length of the returned intrusion buffer.

The possible range of the intruder_len argument is 0to 1058 bytes. If the longword specified by the argument contains a 0after the call to the service, either the service did not find a recordthat matched the user criteria in the intrusion database, or there areno more matching items in the intrusion database.

breakin_block

OpenVMS usage:	record
type:	block of 2 words (unsigned), 1 longword (unsigned), and 1 quadword (unsigned)
access:	write only
mechanism:	by reference

Block to receive various information in the intrusion database about arecord matching the user criteria. The breakin_blockargument is the address of a structure with the following format:

The following table defines the break-in block fields:

flags

Each option has a symbolic name. The $CIADEF macro defines thefollowing valid names:

Each of these options is mutually exclusive.

context

The initial value contained in the unsigned 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 context argument arechanged between calls to the service, SS$_BADCONTEXT will be returned.

Contexts become invalid after one-half hour of non-use. This means thatif you call the $SHOW_INTRUSION service with a wildcard in theuser_criteria argument and do not call the service toget the next matching record within one-half hour, the context becomesinvalid. If the context has become invalid, you must restart yoursearch of the intrusion database from the beginning by resetting thecontext to 0.

Description

The Show Intrusion service returns information about records in theintrusion database that match the criteria you specify.

You can retrieve information about multiple records in the intrusiondatabase by specifying wildcards for the user_criteriaargument. For example, specifying an asterisk (*) for theuser_criteria argument and CIA$M_ALL_RECORDS for theflags argument will return information about allrecords in the database. Specifying TTA4* for theuser_criteria argument and CIA$M_SUSPECTS_ONLY for theflags argument will return information about allsuspects who have had failures on terminal TTA4.

If you specify a wildcard string for the user_criteriaargument, you must also include a context argument.Because the service can only return information about one intrusionrecord at a time, you must call the service repeatedly to retrieveinformation about more than one record. The service will returnSS$_NOMOREITEMS when information about all of the matching records hasbeen returned. No intrusion information is returned from the call thatreturns SS$_NOMOREITEMS.

Required Access or Privileges

SECURITY privilege is required.

Required Quota

None

Related Services

$DELETE_INTRUSION, $SCAN_INTRUSION

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The user_criteria or context argument cannot be read, or the intruder, intruder_len, breakin_block, or context argument cannot be written.
SS$_BADBUFLEN	The length of one of the specified arguments is out of range.
SS$_BADCONTEXT	The context argument did not contain a 0 on the first call to the service. The context argument's value changed between consecutive calls to the service.
SS$_BADPARAM	An invalid value was specified in the flags argument, or mutually exclusive options were specified in the flags argument.
SS$_NOMOREITEMS	All items matching the specified criteria have been returned.
SS$_NOSECURITY	The caller does not have SECURITY privilege.
This service can also return any of the following messages passed from the security server:
SECSRV$_NOSUCHINTRUDER	No records matching the specified criteria were found in the intrusion database.
SECSRV$_SERVERNOTACTIVE	The security server is not currently active. Try the request again later.

Returns the address of a 64-bit signal array. A 32-bit signal array anda mechanism array are passed to a condition handler when it is called.$SIGNAL_ARRAY_64 provides the address of the 64-bit signal array, whichmight be required for programs that use 64-bit address space.

This service accepts 64-bit addresses.

Format

SYS$SIGNAL_ARRAY_64 mcharg, sigarg_64

C Prototype

int sys$signal_array_64 (unsigned __int64 mcharg, unsigned __int64sigarg_64);

Arguments

mcharg

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

The mechanism array. The mcharg argument is the 32- or64-bit address of this array, which was passed to the conditionhandler. $SIGNAL_ARRAY_64 uses this structure to determine the 64-bitsignal array address.

sigarg_64

OpenVMS usage:	64-bit signal array
type:	vector quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference, array reference

The 32- or 64-bit address of the 64-bit signal array is returned inthis argument.

Description

$SIGNAL_ARRAY_64 provides the address of the 64-bit version of thesignal array for condition handlers that need it. It is normally neededonly by applications that use 64-bit address space and want to handleerrors involving addresses in that region.

For example, if an access violation occurs on a 64-bit address, the32-bit signal array passed to the handler will contain only the low 32bits of the effective address, because each entry is a longword. The64-bit signal array, which can be obtained using this service, containsquadword entries, so the 64-bit address can be fully expressed.

Required Access or Privileges

None

Required Quota

None

Related Services

$PUTMSG, which accepts either a 32-bit or 64-bit signal array as anargument.

Condition Values Returned

SS$_NORMAL	The service completed succesfully.
SS$_ACCVIO	The sigarg_64 argument cannot be written.
SS$_BADPARAM	The mcharg argument is not a mechanism array in the expected format.

Writes a user-specified message to the system error log file, precedingit with the date and time.

Format

SYS$SNDERR msgbuf

C Prototype

int sys$snderr (void *msgbuf);

Argument

msgbuf

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

Message to be written to the error log file. Themsgbuf argument is the address of a character stringdescriptor pointing to the message text.

Description

The Send Message to Error Logger service writes a user-specifiedmessage to the system error log file, preceding it with the date andtime. The $SNDERR service requires system dynamic memory.

Required Access or Privileges

To send a message to the error log file, the calling process must haveBUGCHK privilege.

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, $SNDJBC,$SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The message buffer or buffer descriptor cannot be read by the caller.
SS$_INSFMEM	The system dynamic memory is insufficient for completing the service.
SS$_NOPRIV	The process does not have the required BUGCHK privilege.

Creates, stops, and manages queues and the batch and print jobs inthose queues. The $SNDJBC service completes asynchronously; tosynchronize the completion of most operations, use the Send to JobController and Wait ($SNDJBCW) service.

Format

SYS$SNDJBC [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr] [,astprm]

C Prototype

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

Arguments

efn

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

Number of the event flag to be set when $SNDJBC completes. Theefn argument is a longword containing this number;however, $SNDJBC uses only the low-order byte.

When you queue the request, $SNDJBC clears the specified event flag (orevent flag 0 if efn was not specified). Then, when theoperation completes, $SNDJBC sets the specified event flag (or eventflag 0).

func

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

Function code specifying the function that $SNDJBC is to perform. Thefunc argument is a word containing this function code.The $SJCDEF macro defines the names of each function code.

You can specify only one function code in a single call to $SNDJBC.Most function codes require or allow for additional information to bepassed in the call. You pass this information by using theitmlst argument, which specifies a list of one or moreitem descriptors. Each item descriptor in turn specifies an item code,which modifies, restricts, or otherwise affects the action designatedby the function code.

nullarg

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

Placeholding argument reserved to HP.

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 whichspecifies an item code. The item list is terminated by an item code of0 or by a longword of 0. The following diagram depicts the structure ofa single item descriptor:

The following table defines the item descriptor fields:

The item codes' symbolic names have the following format:

There are three types of item code:

• Boolean item code. Boolean item codes specify a true or false value: the form SJC$_code specifies a true value; SJC$_NO_code specifies a false value. The default value for the Boolean item codes is false. For all Boolean item codes, the buffer length, buffer address, and return length fields of the item descriptor must be 0.
• Input value item code. Input value item codes specify an input value to be used by $SNDJBC. The buffer length and buffer address fields of the item descriptor must be nonzero; the return length field must be 0. Specific buffer length requirements are given in the description of each item code.
• Output value item code. Output value item codes specify a buffer for information returned by $SNDJBC. The buffer length and buffer address fields of the item descriptor must be nonzero; the return length field can be 0 or nonzero. Specific buffer length requirements are given in the description of each item code.

Several item codes specify a queue name, form name, or characteristicname. For these item codes, the buffer must specify a string containingfrom 1 to 31 characters, exclusive of spaces, tabs, and nullcharacters, which are ignored. Allowable characters in the string areuppercase alphabetic characters, lowercase alphabetic characters (whichare converted to uppercase), numeric characters, the dollar sign ($),and the underscore (_).

iosb

At request initiation, $SNDJBC sets the value of the quadword I/Ostatus block to 0. When the requested operation completes, $SNDJBCwrites a condition value in the first longword of the I/O status block.It writes the value 0 into the second longword; this longword is unusedand reserved for future use.

The condition values returned by $SNDJBC in the I/O status block areusually condition values from the JBC facility. These condition valuesare defined by the $JBCMSGDEF macro. In some cases, the condition valuereturned by $SNDJBC can be an error return from a system service or anOpenVMS RMS service that is used in executing the request. For theSJC$_SYNCHRONIZE_JOB request, the condition value returned is thecompletion status of the requested job.

The condition values returned from the JBC facility are listed in theCondition Values Returned in the I/O Status Block section.

Though this argument is optional, HP strongly recommends that youspecify it, for the following reasons:

• If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
• If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
• The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $SNDJBC service. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $SNDJBC, you must check the condition values returned in both R0 and the I/O status block.

astadr

If specified, the AST routine executes at the same access mode as thecaller of $SNDJBC.

astprm

SJC$_ABORT_JOB

Aborts the execution of the current job from an output execution queueor the job you specified from a batch queue. By default, the job isdeleted. However, for a restartable job, you can requeue it to the samequeue or to another queue.

You must specify one of the following input value item codes:

SJC$_ENTRY_NUMBER
SJC$_QUEUE

You must specify the following input value item code for batch jobs:

SJC$_ENTRY_NUMBER

You can specify the following optional input value or Boolean itemcodes:

SJC$_DESTINATION_QUEUE	---
SJC$_HOLD	SJC$_NO_HOLD
SJC$_PRIORITY	---
SJC$_REQUEUE	---

SJC$_ADD_FILE

Adds a file to the open job owned by the requesting process. You usethis operation as part of a sequence of calls to the $SNDJBC service tocreate a job with one or more files. The first call in the sequencespecifies the SJC$_CREATE_JOB operation to create an open job. Eachsubsequent SJC$_ADD_FILE request associates an additional file with thejob. Finally, you make an SJC$_CLOSE_JOB request to complete the batchor print job specification.

To create a job that contains only one file, you can make a single callto $SNDJBC that specifies the SJC$_ENTER_FILE function code.

You must specify one of the following input value item codes:

SJC$_FILE_IDENTIFICATION
SJC$_FILE_SPECIFICATION

You can specify the following input value or Boolean item codes:

SJC$_DELETE_FILE	SJC$_NO_DELETE_FILE
SJC$_DOUBLE_SPACE	SJC$_NO_DOUBLE_SPACE
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_COPIES	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_SETUP_MODULES	SJC$_NO_FILE_SETUP_MODULES
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FIRST_PAGE	SJC$_NO_FIRST_PAGE
SJC$_LAST_PAGE	SJC$_NO_LAST_PAGE
SJC$_PAGE_HEADER	SJC$_NO_PAGE_HEADER
SJC$_PAGINATE	SJC$_NO_PAGINATE
SJC$_PASSALL	SJC$_NO_PASSALL

SJC$_ALTER_JOB

Alters the parameters of an existing job that is not currentlyexecuting.

You must specify the following input value item code:

SJC$_ENTRY_NUMBER

You can specify the following input value or Boolean item codes:

SJC$_AFTER_TIME	SJC$_NO_AFTER_TIME
SJC$_CHARACTERISTIC_NAME	SJC$_NO_CHARACTERISTICS
SJC$_CHARACTERISTIC_NUMBER	---
---	SJC$_NO_CHECKPOINT_DATA
SJC$_CLI	SJC$_NO_CLI
SJC$_CPU_LIMIT	SJC$_NO_CPU_LIMIT
---	SJC$_NO_DELETE_FILE
SJC$_DESTINATION_QUEUE	---
SJC$_DOUBLE_SPACE	SJC$_NO_DOUBLE_SPACE
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_COPIES	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_SETUP_MODULES	SJC$_NO_FILE_SETUP_MODULES
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FIRST_PAGE	SJC$_NO_FIRST_PAGE
SJC$_FORM_NAME	---
SJC$_FORM_NUMBER	---
SJC$_HOLD	SJC$_NO_HOLD
SJC$_JOB_COPIES	---
SJC$_JOB_DEFAULT_RETAIN	---
SJC$_JOB_ERROR_RETAIN	---
SJC$_JOB_NAME	---
SJC$_JOB_RETAIN	---
SJC$_JOB_RETAIN_TIME	---
SJC$_LAST_PAGE	SJC$_NO_LAST_PAGE
SJC$_LOG_DELETE	SJC$_NO_LOG_DELETE
SJC$_LOG_QUEUE	---
SJC$_LOG_SPECIFICATION	SJC$_NO_LOG_SPECIFICATION
SJC$_LOG_SPOOL	SJC$_NO_LOG_SPOOL
SJC$_LOWERCASE	SJC$_NO_LOWERCASE
SJC$_NOTE	SJC$_NO_NOTE
SJC$_NOTIFY	SJC$_NO_NOTIFY
SJC$_OPERATOR_REQUEST	SJC$_NO_OPERATOR_REQUEST
SJC$_PAGE_HEADER	SJC$_NO_PAGE_HEADER
SJC$_PAGINATE	SJC$_NO_PAGINATE
SJC$_PARAMETER_1 through 8	SJC$_NO_PARAMETERS
SJC$_PASSALL	SJC$_NO_PASSALL
SJC$_PRIORITY	---
SJC$_QUEUE	---
SJC$_RAD	SJC$_NO_RAD
SJC$_RESTART	SJC$_NO_RESTART
SJC$_WSDEFAULT	SJC$_NO_WSDEFAULT
SJC$_WSEXTENT	SJC$_NO_WSEXTENT
SJC$_WSQUOTA	SJC$_NO_WSQUOTA

If you specify the SJC$_QUEUE item code, the $SNDJBC service verifiesthat the selected job entry exists on the specified queue beforemodifying the job.

SJC$_ALTER_QUEUE

Alters the parameters of a queue. The execution of current jobs isunaffected.

You must specify the following input value item code:

SJC$_QUEUE

You can specify the following input value or Boolean item codes:

SJC$_BASE_PRIORITY	---
SJC$_CHARACTERISTIC_NAME	SJC$_NO_CHARACTERISTICS
SJC$_CHARACTERISTIC_NUMBER	---
SJC$_CLOSE_QUEUE	---
SJC$_CPU_DEFAULT	SJC$_NO_CPU_DEFAULT
SJC$_CPU_LIMIT	SJC$_NO_CPU_LIMIT
SJC$_DEFAULT_FORM_NAME	---
SJC$_DEFAULT_FORM_NUMBER	---
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_BURST_ONE	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_FLAG_ONE	---
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FILE_TRAILER_ONE	---
SJC$_FORM_NAME	---
SJC$_FORM_NUMBER	---
SJC$_GENERIC_SELECTION	SJC$_NO_GENERIC_SELECTION
SJC$_JOB_BURST	SJC$_NO_JOB_BURST
SJC$_JOB_FLAG	SJC$_NO_JOB_FLAG
SJC$_JOB_LIMIT	---
SJC$_JOB_RESET_MODULES	SJC$_NO_JOB_RESET_MODULES
SJC$_JOB_SIZE_MAXIMUM	SJC$_NO_JOB_SIZE_MAXIMUM
SJC$_JOB_SIZE_MINIMUM	SJC$_NO_JOB_SIZE_MINIMUM
SJC$_JOB_SIZE_SCHEDULING	SJC$_NO_JOB_SIZE_SCHEDULING
SJC$_JOB_TRAILER	SJC$_NO_JOB_TRAILER
SJC$_OPEN_QUEUE	---
SJC$_OWNER_UIC	---
SJC$_PAGINATE	SJC$_NO_PAGINATE
SJC$_PROTECTION	---
SJC$_QUEUE_DESCRIPTION	SJC$_NO_QUEUE_DESCRIPTION
SJC$_RAD	SJC$_NO_RAD
SJC$_RECORD_BLOCKING	SJC$_NO_RECORD_BLOCKING
SJC$_RETAIN_ALL_JOBS	SJC$_NO_RETAIN_JOBS
SJC$_RETAIN_ERROR_JOBS	---
SJC$_SWAP	SJC$_NO_SWAP
SJC$_WSDEFAULT	SJC$_NO_WSDEFAULT
SJC$_WSEXTENT	SJC$_NO_WSEXTENT
SJC$_WSQUOTA	SJC$_NO_WSQUOTA

SJC$_ASSIGN_QUEUE

Assigns a logical queue to an execution queue. The SJC$_QUEUE item codespecifies the logical queue; the SJC$_DESTINATION_QUEUE item codespecifies the execution queue.

You must specify the following input value item codes:

SJC$_DESTINATION_QUEUE
SJC$_QUEUE

SJC$_BATCH_CHECKPOINT

Establishes a checkpoint in a batch job. No operation is performed ifthe requesting process is not a batch process.

You must specify the following input value item code:

SJC$_CHECKPOINT_DATA

SJC$_CLOSE_DELETE

Deletes the open job owned by the requesting process. No item codes areallowed.

SJC$_CLOSE_JOB

Completes the specification of the open job owned by the requestingprocess and places the job in the queue specified in theSJC$_CREATE_JOB request that opened the job. If the SJC$_CLOSE_JOBrequest completes successfully, the job is no longer an open job; itbecomes a normal batch or print job.

You can specify the following output value item code:

SJC$_JOB_STATUS_OUTPUT

SJC$_CREATE_JOB

Creates an open job for the requesting process. If the process alreadyowns an open job, that job is deleted.

An open job is a batch or print job that has not yet been completelyspecified. After you make the SJC$_CREATE_JOB request to open the job,you can make subsequent calls to $SNDJBC using the SJC$_ADD_FILEfunction code to specify the files associated with the job. Finally,you can complete the job specification with an SJC$_CLOSE_JOB request.If the SJC$_CREATE_JOB operation completes successfully, the open jobcreated is given an entry number; the job is not assigned to the queuespecified in the SJC$_CREATE_JOB operation until the SJC$_CLOSE_JOBrequest completes successfully.

You must specify the following input value item code:

SJC$_QUEUE

You can specify the following input value or Boolean item codes:

SJC$_ACCOUNT_NAME	---
SJC$_AFTER_TIME	SJC$_NO_AFTER_TIME
SJC$_CHARACTERISTIC_NAME	SJC$_NO_CHARACTERISTICS
SJC$_CHARACTERISTIC_NUMBER	---
SJC$_CLI	SJC$_NO_CLI
SJC$_CPU_LIMIT	SJC$_NO_CPU_LIMIT
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_BURST_ONE	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_FLAG_ONE	---
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FILE_TRAILER_ONE	---
SJC$_FIRST_PAGE	SJC$_NO_FIRST_PAGE
SJC$_FORM_NAME	---
SJC$_FORM_NUMBER	---
SJC$_HOLD	SJC$_NO_HOLD
SJC$_JOB_COPIES	---
SJC$_JOB_DEFAULT_RETAIN	---
SJC$_JOB_ERROR_RETAIN	---
SJC$_JOB_NAME	---
SJC$_JOB_RETAIN	---
SJC$_JOB_RETAIN_TIME	---
SJC$_LAST_PAGE	SJC$_NO_LAST_PAGE
SJC$_LOG_DELETE	SJC$_NO_LOG_DELETE
SJC$_LOG_QUEUE	---
SJC$_LOG_SPECIFICATION	SJC$_NO_LOG_SPECIFICATION
SJC$_LOG_SPOOL	SJC$_NO_LOG_SPOOL
SJC$_LOWERCASE	SJC$_NO_LOWERCASE
SJC$_NOTE	SJC$_NO_NOTE
SJC$_NOTIFY	SJC$_NO_NOTIFY
SJC$_OPERATOR_REQUEST	SJC$_NO_OPERATOR_REQUEST
SJC$_PARAMETER_1 through 8	SJC$_NO_PARAMETERS
SJC$_PRIORITY	---
SJC$_RAD	SJC$_NO_RAD
SJC$_RESTART	SJC$_NO_RESTART
SJC$_UIC	---
SJC$_USERNAME	---
SJC$_WSDEFAULT	SJC$_NO_WSDEFAULT
SJC$_WSEXTENT	SJC$_NO_WSEXTENT
SJC$_WSQUOTA	SJC$_NO_WSQUOTA

You can specify the following output value item code:

SJC$_ENTRY_NUMBER_OUTPUT

SJC$_CREATE_QUEUE

Creates a queue. If the queue already exists and is not stopped, thisrequest performs no operation. However, if the queue already exists andis stopped, the request alters the parameters of the queue based on theitem codes specified in the request; if you specify theSJC$_CREATE_START item code, the request starts the queue.

You must specify the following input value item code:

SJC$_QUEUE

You can specify the following input value or Boolean item codes:

SJC$_AUTOSTART_ON	---
SJC$_BASE_PRIORITY	---
SJC$_BATCH	SJC$_NO_BATCH
SJC$_CHARACTERISTIC_NAME	SJC$_NO_CHARACTERISTICS
SJC$_CHARACTERISTIC_NUMBER	---
SJC$_CLOSE_QUEUE	---
SJC$_CPU_DEFAULT	SJC$_NO_CPU_DEFAULT
SJC$_CPU_LIMIT	SJC$_NO_CPU_LIMIT
SJC$_CREATE_START	---
SJC$_DEFAULT_FORM_NAME	---
SJC$_DEFAULT_FORM_NUMBER	---
SJC$_DEVICE_NAME	---
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_BURST_ONE	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_FLAG_ONE	---
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FILE_TRAILER_ONE	---
SJC$_FORM_NAME	---
SJC$_FORM_NUMBER	---
SJC$_GENERIC_QUEUE	SJC$_NO_GENERIC_QUEUE
SJC$_GENERIC_SELECTION	SJC$_NO_GENERIC_SELECTION
SJC$_GENERIC_TARGET	---
SJC$_JOB_BURST	SJC$_NO_JOB_BURST
SJC$_JOB_FLAG	SJC$_NO_JOB_FLAG
SJC$_JOB_LIMIT	---
SJC$_JOB_RESET_MODULES	SJC$_NO_JOB_RESET_MODULES
SJC$_JOB_SIZE_MAXIMUM	SJC$_NO_JOB_SIZE_MAXIMUM
SJC$_JOB_SIZE_MINIMUM	SJC$_NO_JOB_SIZE_MINIMUM
SJC$_JOB_SIZE_SCHEDULING	SJC$_NO_JOB_SIZE_SCHEDULING
SJC$_JOB_TRAILER	SJC$_NO_JOB_TRAILER
SJC$_LIBRARY_SPECIFICATION	SJC$_NO_LIBRARY_SPECIFICATION
SJC$_OPEN_QUEUE	---
SJC$_OWNER_UIC	---
SJC$_PAGINATE	SJC$_NO_PAGINATE
SJC$_PRINTER	---
SJC$_PROCESSOR	SJC$_NO_PROCESSOR
SJC$_PROTECTION	---
SJC$_QUEUE_DESCRIPTION	SJC$_NO_QUEUE_DESCRIPTION
SJC$_QUEUE_MANAGER_NAME	---
SJC$_RAD	SJC$_NO_RAD
SJC$_RECORD_BLOCKING	SJC$_NO_RECORD_BLOCKING
SJC$_RETAIN_ALL_JOBS	SJC$_NO_RETAIN_JOBS
SJC$_RETAIN_ERROR_JOBS	---
SJC$_SCSNODE_NAME	---
SJC$_SERVER	---
SJC$_SWAP	SJC$_NO_SWAP
SJC$_TERMINAL	SJC$_NO_TERMINAL
SJC$_WSDEFAULT	SJC$_NO_WSDEFAULT
SJC$_WSEXTENT	SJC$_NO_WSEXTENT
SJC$_WSQUOTA	SJC$_NO_WSQUOTA

SJC$_DEASSIGN_QUEUE

Deassigns a logical queue from an execution queue.

You must specify the following input value item code:

SJC$_QUEUE

SJC$_DEFINE_CHARACTERISTIC

Defines a characteristic name and number and inserts this definitioninto the queue file. The characteristic name can be up to 31 charactersin length. Each characteristic name must have a unique number in therange 0 to 127. If the characteristic name is already defined, therequest alters the definition of the characteristic.

A job cannot execute on an execution queue unless the queue possessesall the characteristics possessed by the job; the queue can possessadditional characteristics and the job will still execute.

You must specify the following input value item codes:

SJC$_CHARACTERISTIC_NAME
SJC$_CHARACTERISTIC_NUMBER

SJC$_DEFINE_FORM

Defines a form name and number, as well as other physical attributes ofthe paper stock used in printers, and inserts this definition into thesystem job queue file. If the form name is already defined, thisrequest alters the definition of the form.

Forms are used only by output execution queues and print jobs. A printjob cannot execute unless the stock name of a form specified for thequeue is the same as the stock name specified for the job. The stockname of a form, which you specify by using the SJC$_FORM_STOCK itemcode, specifies the paper stock used by the printer. Other item codesspecify printing parameters for a job such as the margins, length ofpaper, and so on.

Each form must have a unique number. Numbers can range from 0 to 9999.When a new queue file is created, the system supplies the definition ofa form named DEFAULT with number 0 and default characteristics.

You must specify the following input value item codes:

SJC$_FORM_NAME
SJC$_FORM_NUMBER

You can specify the following input value or Boolean item codes:

SJC$_FORM_DESCRIPTION	---
SJC$_FORM_LENGTH	---
SJC$_FORM_MARGIN_BOTTOM	---
SJC$_FORM_MARGIN_LEFT	---
SJC$_FORM_MARGIN_RIGHT	---
SJC$_FORM_MARGIN_TOP	---
SJC$_FORM_SETUP_MODULES	SJC$_NO_FORM_SETUP_MODULES
SJC$_FORM_SHEET_FEED	SJC$_NO_FORM_SHEET_FEED
SJC$_FORM_STOCK	---
SJC$_FORM_TRUNCATE	SJC$_NO_FORM_TRUNCATE
SJC$_FORM_WIDTH	---
SJC$_FORM_WRAP	SJC$_NO_FORM_WRAP
SJC$_PAGE_SETUP_MODULES	SJC$_NO_PAGE_SETUP_MODULES

SJC$_DELETE_CHARACTERISTIC

Deletes the definition of a characteristic name.

You must specify the following input value item code:

SJC$_CHARACTERISTIC_NAME

SJC$_DELETE_FORM

Deletes the definition of a form name. There must be no queues or jobsthat reference the form.

You must specify the following input value item code:

SJC$_FORM_NAME

SJC$_DELETE_JOB

Deletes a job from the system job queue file. If the job is currentlyexecuting, it is aborted. If you specify the SJC$_QUEUE item code, the$SNDJBC service verifies that the selected job entry exists on thespecified queue before deleting the job.

You must specify the following input value item code:

SJC$_ENTRY_NUMBER

You can specify the following input value item code:

SJC$_QUEUE

If you specify the SJC$_QUEUE item code, the $SNDJBC service verifiesthat the selected job entry exists on the specified queue beforedeleting the job.

SJC$_DELETE_QUEUE

Deletes a queue and all of the jobs in the queue. The queue must bestopped, and there must be no other queues or jobs that reference thequeue.

You must specify the following input value item code:

SJC$_QUEUE

SJC$_DELETE_QUEUE_MANAGER

Removes all references to the specified queue manager from the sharedmaster file. It also deletes the queue and journal files associatedwith the queue manager. A queue manager must be stopped to be deleted.

You must specify the following input value item code:

SJC$_QUEUE_MANAGER_NAME

SJC$_DISABLE_AUTOSTART

Disables autostart on a node. By default, SJC$_DISABLE_AUTOSTARTaffects the requesting node. To disable autostart on a node other thanthe node from which the $SNDJBC request is sent, use theSJC$_SCSNODE_NAME item code to specify the affected node.

Disabling autostart on a node forces the appropriate queue manager toperform these tasks:

• Prevent autostart queues from failing over to the node.
• Mark all of that queue manager's autostart queues on the node as "stop pending" in preparation for a planned shutdown, allowing jobs currently executing on the queues to complete.
• Force all autostart queues with failover lists to fail over to the next available node in the queue manager's failover list on which autostart is enabled. Each queue fails over when all jobs currently executing on any of that queue manager's queues on the node have completed.

You can specify the following input value item codes:

SJC$_QUEUE_MANAGER_NAME
SJC$_SCSNODE_NAME

For more information, refer to the HP OpenVMS System Manager's Manual.

SJC$_ENABLE_AUTOSTART

Notifies the appropriate queue manager process that a node hasprogressed sufficiently in its startup procedure that batch and printjobs should execute.

By default, SJC$_ENABLE_AUTOSTART affects the requesting node. Toenable autostart on a node other than the node from which the $SNDJBCrequest is sent, use the SJC$_SCSNODE_NAME item code to specify theaffected node. Once autostart is enabled, the queue manager starts allautostart-active queues on the appropriate node.

When a node reboots, autostart is disabled until theSJC$_ENABLE_AUTOSTART request is entered.

You can specify the following input value item codes:

SJC$_QUEUE_MANAGER_NAME
SJC$_SCSNODE_NAME

For more information, refer to the HP OpenVMS System Manager's Manual.

SJC$_ENTER_FILE

Creates a job containing one file and places the job in the specifiedqueue. To create a job with more than one file, you must make asequence of calls to the $SNDJBC service using the SJC$_CREATE_JOB,SJC$_ADD_FILE, and SJC$_CLOSE_JOB function codes.

You must specify the following input value item code:

SJC$_QUEUE

You must specify one of the following input value item codes:

SJC$_FILE_IDENTIFICATION
SJC$_FILE_SPECIFICATION

You can specify the following input value or Boolean item codes:

SJC$_ACCOUNT_NAME	---
SJC$_AFTER_TIME	SJC$_NO_AFTER_TIME
SJC$_CHARACTERISTIC_NAME	SJC$_NO_CHARACTERISTICS
SJC$_CHARACTERISTIC_NUMBER	---
SJC$_CLI	SJC$_NO_CLI
SJC$_CPU_LIMIT	SJC$_NO_CPU_LIMIT
SJC$_DELETE_FILE	SJC$_NO_DELETE_FILE
SJC$_DOUBLE_SPACE	SJC$_NO_DOUBLE_SPACE
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_COPIES	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_SETUP_MODULES	SJC$_NO_FILE_SETUP_MODULES
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FIRST_PAGE	SJC$_NO_FIRST_PAGE
SJC$_FORM_NAME	---
SJC$_FORM_NUMBER	---
SJC$_HOLD	SJC$_NO_HOLD
SJC$_JOB_COPIES	---
SJC$_JOB_DEFAULT_RETAIN	---
SJC$_JOB_ERROR_RETAIN	---
SJC$_JOB_NAME	---
SJC$_JOB_RETAIN	---
SJC$_JOB_RETAIN_TIME	---
SJC$_LAST_PAGE	SJC$_NO_LAST_PAGE
SJC$_LOG_DELETE	SJC$_NO_LOG_DELETE
SJC$_LOG_QUEUE	---
SJC$_LOG_SPECIFICATION	SJC$_NO_LOG_SPECIFICATION
SJC$_LOG_SPOOL	SJC$_NO_LOG_SPOOL
SJC$_LOWERCASE	SJC$_NO_LOWERCASE
SJC$_NOTE	SJC$_NO_NOTE
SJC$_NOTIFY	SJC$_NO_NOTIFY
SJC$_OPERATOR_REQUEST	SJC$_NO_OPERATOR_REQUEST
SJC$_PAGE_HEADER	SJC$_NO_PAGE_HEADER
SJC$_PAGINATE	SJC$_NO_PAGINATE
SJC$_PARAMETER_1 through 8	SJC$_NO_PARAMETERS
SJC$_PASSALL	SJC$_NO_PASSALL
SJC$_PRIORITY	---
SJC$_RAD	SJC$_NO_RAD
SJC$_RESTART	SJC$_NO_RESTART
SJC$_UIC	---
SJC$_USERNAME	---
SJC$_WSDEFAULT	SJC$_NO_WSDEFAULT
SJC$_WSEXTENT	SJC$_NO_WSEXTENT
SJC$_WSQUOTA	SJC$_NO_WSQUOTA

You can specify the following output value item codes:

SJC$_ENTRY_NUMBER_OUTPUT
SJC$_JOB_STATUS_OUTPUT

SJC$_MERGE_QUEUE

Requeues all jobs in the queue specified by the item code SJC$_QUEUE tothe queue specified by the item code SJC$_DESTINATION_QUEUE. Theexecution of current jobs is unaffected.

You must specify the following input value item codes:

SJC$_DESTINATION_QUEUE
SJC$_QUEUE

SJC$_PAUSE_QUEUE

Pauses the execution of current jobs in the specified queue andprevents the starting of jobs in that queue.

You must specify the following input value item code:

SJC$_QUEUE

SJC$_RESET_QUEUE

Resets the specified queue by (1) terminating and deleting eachexecuting job that is not restartable, (2) terminating and requeuingeach executing job that is restartable, and (3) stopping the queue.

You must specify the following input value item code:

SJC$_QUEUE

SJC$_START_ACCOUNTING

This request performs two functions. If you specify theSJC$_ACCOUNTING_TYPES item code, the request enables recording of thespecified types of accounting records; if you do not specifySJC$_ACCOUNTING_TYPES, the request starts the accounting manager andopens the system accounting file.

You can specify the following input value or Boolean item codes:

SJC$_ACCOUNTING_TYPES
SJC$_NEW_VERSION

SJC$_START_QUEUE

Permits the starting of jobs in the specified queue. If the queue waspaused, current jobs are resumed.

You must specify the following input value item code:

SJC$_QUEUE

You can specify the following input value or Boolean item codes:

SJC$_ALIGNMENT_MASK	---
SJC$_ALIGNMENT_PAGES	---
SJC$_AUTOSTART_ON	---
SJC$_BASE_PRIORITY	---
SJC$_BATCH	SJC$_NO_BATCH
SJC$_CHARACTERISTIC_NAME	SJC$_NO_CHARACTERISTICS
SJC$_CHARACTERISTIC_NUMBER	---
SJC$_CLOSE_QUEUE	---
SJC$_CPU_DEFAULT	SJC$_NO_CPU_DEFAULT
SJC$_CPU_LIMIT	SJC$_NO_CPU_LIMIT
SJC$_DEFAULT_FORM_NAME	---
SJC$_DEFAULT_FORM_NUMBER	---
SJC$_DEVICE_NAME	---
SJC$_FILE_BURST	SJC$_NO_FILE_BURST
SJC$_FILE_BURST_ONE	---
SJC$_FILE_FLAG	SJC$_NO_FILE_FLAG
SJC$_FILE_FLAG_ONE	---
SJC$_FILE_TRAILER	SJC$_NO_FILE_TRAILER
SJC$_FILE_TRAILER_ONE	---
SJC$_FORM_NAME	---
SJC$_FORM_NUMBER	---
SJC$_GENERIC_QUEUE	SJC$_NO_GENERIC_QUEUE
SJC$_GENERIC_SELECTION	SJC$_NO_GENERIC_SELECTION
SJC$_GENERIC_TARGET	---
SJC$_JOB_BURST	SJC$_NO_JOB_BURST
SJC$_JOB_FLAG	SJC$_NO_JOB_FLAG
SJC$_JOB_LIMIT	---
SJC$_JOB_RESET_MODULES	SJC$_NO_JOB_RESET_MODULES
SJC$_JOB_SIZE_MAXIMUM	SJC$_NO_JOB_SIZE_MAXIMUM
SJC$_JOB_SIZE_MINIMUM	SJC$_NO_JOB_SIZE_MINIMUM
SJC$_JOB_SIZE_SCHEDULING	SJC$_NO_JOB_SIZE_SCHEDULING
SJC$_JOB_TRAILER	SJC$_NO_JOB_TRAILER
SJC$_LIBRARY_SPECIFICATION	SJC$_NO_LIBRARY_SPECIFICATION
SJC$_NEXT_JOB	---
SJC$_OPEN_QUEUE	---
SJC$_OWNER_UIC	---
SJC$_PAGINATE	SJC$_NO_PAGINATE
SJC$_PROCESSOR	SJC$_NO_PROCESSOR
SJC$_PROTECTION	---
SJC$_QUEUE_DESCRIPTION	SJC$_NO_QUEUE_DESCRIPTION
SJC$_RAD	SJC$_NO_RAD
SJC$_RECORD_BLOCKING	SJC$_NO_RECORD_BLOCKING
SJC$_RELATIVE_PAGE	---
SJC$_RETAIN_ALL_JOBS	SJC$_NO_RETAIN_JOBS
SJC$_RETAIN_ERROR_JOBS	---
SJC$_SCSNODE_NAME	---
SJC$_SEARCH_STRING	---
SJC$_SWAP	SJC$_NO_SWAP
SJC$_TERMINAL	SJC$_NO_TERMINAL
SJC$_TOP_OF_FILE	---
SJC$_WSDEFAULT	SJC$_NO_WSDEFAULT
SJC$_WSEXTENT	SJC$_NO_WSEXTENT
SJC$_WSQUOTA	SJC$_NO_WSQUOTA

SJC$_START_QUEUE_MANAGER

Starts the clusterwide queue manager for the batch and print queuingsystem. It also opens the queue database.

The SJC$_START_QUEUE_MANAGER request has the following five uses:

• To create a queue database and initially start the queue manager, issue a SJC$_START_QUEUE_MANAGER request with the SJC$_NEW_VERSION item code. See the description of the SJC$_NEW_VERSION item code for more information. Once the queue manager has been started, it will remain running unless it is explicitly stopped with an SJC$_STOP_QUEUE_MANAGER request.
• If an SJC$_STOP_QUEUE_MANAGER request has been specified, issue a SJC$_START_QUEUE_MANAGER request to restart the queue manager.
• In an OpenVMS Cluster environment, issue an SJC$_START_QUEUE_MANAGER request with the SJC$_QUEUE_MANAGER_NODES item code to modify the list of preferred nodes on which the queue manager can run. See the description of the SJC_QUEUE_MANAGER_NODES item code for more information.
• In a cluster, issue an SJC$_START_QUEUE_MANAGER request to ensure that the queue manager process is executing on the most preferred, available node. If the queue manager is not running on the most preferred, available node, the queue manager will be moved to that node without interruption of service. If you are using the default node list (*), the queue manager will not move. For more information, see the description of the SJC$_QUEUE_MANAGER_NODES item code.
• To create additional queue managers, issue an SJC$_START_QUEUE_MANAGER request with the SJC$_ADD_QUEUE_MANAGER and SJC$_QUEUE_MANAGER_NAME item codes. Note that the queue manager name must be different from the name of any queue manager currently defined. For more information about creating multiple queue managers, refer to the HP OpenVMS System Manager's Manual.

You can specify the following input value or Boolean item codes:

SJC$_ADD_QUEUE_MANAGER
SJC$_NEW_VERSION
SJC$_QUEUE_DIRECTORY
SJC$_QUEUE_MANAGER_NAME
SJC$_QUEUE_MANAGER_NODES

SJC$_STOP_ACCOUNTING

This request performs two functions. If you specify theSJC$_ACCOUNTING_TYPES item code, the request disables recording of thespecified types of accounting records. If you do not specifySJC$_ACCOUNTING_TYPES, the request stops the accounting manager andcloses the system accounting file.

You can specify the following input value item code:

SJC$_ACCOUNTING_TYPES

SJC$_STOP_ALL_QUEUES_ON_NODE

Stops all queues on a specific node. By default, all queues on therequesting node are stopped. To stop all queues on a node other thanthe node from which the $SNDJBC request is sent, use theSJC$_SCSNODE_NAME item code to specify the affected node.

Besides stopping all queues on a specific node, this request abortseach job that is currently executing. Aborted jobs that are restartableare requeued. Queues for which an autostart list has been specifiedfail over to the first available node in the list for which autostartis enabled.

You can specify the following input value item codes:

SJC$_QUEUE_MANAGER_NAME
SJC$_SCSNODE_NAME

SJC$_STOP_QUEUE

Prevents the starting of jobs in the specified queue. The execution ofcurrent jobs is unaffected.

You must specify the following input value item code:

SJC$_QUEUE

SJC$_STOP_QUEUE_MANAGER

Shuts down the appropriate queue manager. It disables autostart on allnodes; stops all queues; aborts each job that is currently executing,requeuing those jobs that are restartable; and closes the files of thequeue database.

You can specify the following input value item code:

SJC$_QUEUE_MANAGER_NAME

SJC$_SYNCHRONIZE_JOB

Waits for the completion of a job, then sets the event flag, executesthe completion AST if you specified astadr, andreturns the completion status of the job to the I/O Status Block,provided you specified the iosb argument.

You must specify one of the following input value item codes:

SJC$_ENTRY_NUMBER
SJC$_QUEUE

If SJC$_QUEUE queue is specified, then you must also specify one of thefollowing:

SJC$_ENTRY_NUMBER
SJC$_JOB_NAME

You can specify the following output value item code:

SJC$_JOB_COMPLETION_STATUS

SJC$_WRITE_ACCOUNTING

Writes an accounting record.

You must specify the following input value item code:

SJC$_ACCOUNTING_MESSAGE

Item Codes

SJC$_ACCOUNT_NAME

Input value item code that specifies the account name of the user onbehalf of whom the request is made. The buffer must specify a stringfrom 1 to 8 characters. By default, the account name for batch andprint jobs is taken from the requesting process.

You need CMKRNL privilege to use this item code.

(Valid for SJC$_CREATE_JOB, SJC$_ENTER_FILE function codes)

SJC$_ACCOUNTING_MESSAGE

Input value item code. It causes the contents of the buffer to beplaced in a "user message" accounting record. The buffer mustspecify a string from 1 to 255 characters.

(Valid for SJC$_WRITE_ACCOUNTING function code)

SJC$_ACCOUNTING_TYPES

Input value item code. It enables or disables accounting-record types.When an accounting-record type is enabled, the event designated by thattype will be recorded in the accounting record. The buffer must containa longword bit vector wherein each bit set specifies anaccounting-record type. Undefined bits must be 0.

The $SJCDEF macro defines the symbolic names for the accounting-recordtypes. Following is a list of each accounting-record type and thesystem event to which it corresponds:

Accounting-Record Type	Corresponding System Event
SJC$V_ACCT_IMAGE	Image terminations
SJC$V_ACCT_LOGIN_FAILURE	Login failures
SJC$V_ACCT_MESSAGE	User messages sent
SJC$V_ACCT_PRINT	Print job terminations
SJC$V_ACCT_PROCESS	Process terminations

The following accounting-record types, when enabled, provide additionalinformation about image and process termination; specifically, theydescribe the type of image or process that has terminated:

Accounting-Record Type	Type of Image or Process
SJC$V_ACCT_BATCH	Batch process
SJC$V_ACCT_DETACHED	Detached process
SJC$V_ACCT_INTERACTIVE	Interactive process
SJC$V_ACCT_NETWORK	Network process
SJC$V_ACCT_SUBPROCESS	Subprocess

(Valid for SJC$_START_ACCOUNTING, SJC$_STOP_ACCOUNTING function codes)

SJC$_ADD_QUEUE_MANAGER

Boolean item code. It specifies that a new queue manager process shouldbe defined in the master file. The operating system allows no more thanfive queue managers in a cluster.

(Valid for SJC$_START_QUEUE_MANAGER function code)

SJC$_AFTER_TIME

SJC$_NO_AFTER_TIME

The SJC$_AFTER_TIME item code is an input value item code. It specifiesthat the job can execute only if the system time is greater than orequal to the quadword time value contained in the buffer. The buffermust contain either an absolute time value or a delta time value;$SNDJBC converts delta time values to absolute time values by addingthe current system time. The time value specified must be in thefuture, or it will be set to the current time.

The SJC$_NO_AFTER_TIME item code is a Boolean item code. It cancels theeffect of a SJC$_AFTER_TIME item code previously specified for the job;the job can execute immediately. It is the default.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_ALIGNMENT_MASK

Boolean item code. It is meaningful only for output execution queuesand only when the SJC$_ALIGNMENT_PAGES item code is also specified. TheSJC$_ALIGNMENT_MASK item code causes the data printed on form alignmentpages to be masked: all alphabetic characters are replaced with theletter X and all numeric characters with the number 9.

(Valid for SJC$_START_QUEUE function code)

SJC$_ALIGNMENT_PAGES

Input value item code. It is meaningful only for output executionqueues. It specifies that the queue be placed in form-alignment stateand that a number of alignment pages be printed. The buffer mustcontain a longword value in the range 1 to 20; this value specifies howmany alignment pages are to be printed.

(Valid for SJC$_START_QUEUE function code)

SJC$_AUTOSTART_ON

Input value item code. For a batch queue, it uses as its value acomma-separated list of the nodes on which the specified queue can belocated. Each node name must be followed by a double colon (::).

For an output queue, it uses as its value a comma-separated list of thenames of the nodes and devices to which the specified queue's outputcan be sent. Each node name must be followed by a double colon, andeach device name can be followed by the optional colon [:].

By specifying this item code, you designate a queue as an autostartqueue. If you specify more than one node name (within an OpenVMSCluster environment), the queue can automatically fail over if the nodeon which the queue is running is removed from the cluster.

This item code cannot be used with the SJC$_SCSNODE_NAME andSJC$_DEVICE_NAME item codes.

For more information, refer to the HP OpenVMS System Manager's Manual.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_BASE_PRIORITY

Input value item code. It is meaningful only for execution queues. Itspecifies the base priority of batch processes initiated from a batchexecution queue or of a symbiont process connected to an outputexecution queue. A symbiont process can control several queues;however, the base priority of the symbiont process is established bythe first queue to which it is connected. The buffer must contain alongword value in the range 0 to 15; this value specifies the basepriority.

By default, the base priority is the value of the system parameterDEFPRI.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_BATCH

SJC$_NO_BATCH

The SJC$_BATCH item code is a Boolean item code. It specifies that thequeue is a batch execution queue or a generic batch queue, and thus canprocess only batch jobs.

The SJC$_BATCH, SJC$_PRINTER, SJC$_SERVER, and SJC$_TERMINAL item codesare mutually exclusive. If none of these item codes are specified, thedefault is SJC$_PRINTER.

The SJC$_NO_BATCH item code is a Boolean item code. It specifies thatthe queue is not a batch queue but rather an output execution orgeneric output queue, and thus can process only print jobs. It is thedefault.

For the SJC$_START_QUEUE function code, SJC$_BATCH and SJC$_NO_BATCHare supported for compatibility with VAX VMS Version 4.n, but might notbe supported in the future.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_CHARACTERISTIC_NAME

SJC$_CHARACTERISTIC_NUMBER

SJC$_NO_CHARACTERISTICS

The SJC$_CHARACTERISTIC_NAME and SJC$_CHARACTERISTIC_NUMBER item codesare both input value item codes. Both specify characteristics for jobsor queues, and they can be used interchangeably. The characteristicsare user defined.

The SJC$_DEFINE_CHARACTERISTIC and SJC$_DELETE_CHARACTERISTIC functioncodes include and delete, respectively, a specified characteristic fromthe system job queue file. A job cannot execute on an execution queueunless the queue possesses all the characteristics possessed by thejob; the queue can possess additional characteristics and the job willstill execute.

The SJC$_CHARACTERISTIC_NAME and SJC$_CHARACTERISTIC_NUMBER item codescan appear as many times as necessary in a single call to $SNDJBC; theset of characteristics so defined in the call completely replaces theset of characteristics defined by a prior call. TheSJC$_NO_CHARACTERISTICS item code cancels all defined characteristicsfor the job or queue. By default, a queue or job has no definedcharacteristics.

The string can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the number oftranslations allowed by the system has been performed. The maximumlength of the final character string is 31 characters; spaces, tabs,and null characters are ignored.

For SJC$_CHARACTERISTIC_NUMBER, the buffer must contain a longwordvalue in the range 0 to 127. This number identifies a characteristic.

SJC$_NO_CHARACTERISTICS is a Boolean item code.

(The following function codes are valid for SJC_CHARACTERISTIC_NAMEitem code:

SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_DEFINE_CHARACTERISTIC
SJC$_DELETE_CHARACTERISTIC
SJC$_ENTER_FILE
SJC$_START_QUEUE)

(The following function codes are valid for SJC$_CHARACTERISTIC_NUMBERitem code:

SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_DEFINE_CHARACTERISTIC
SJC$_ENTER_FILE
SJC$_START_QUEUE)

SJC$_CHECKPOINT_DATA

Input value item code. It specifies the value of the DCL symbolBATCH$RESTART for a batch job that is restarted. The buffer mustcontain a string no longer than 255 characters; this string is thevalue of the symbol BATCH$RESTART.

(Valid for SJC$_BATCH_CHECKPOINT function code)

SJC$_NO_CHECKPOINT_DATA

Boolean item code. It cancels a previous specification of theBATCH$RESTART symbol; the SJC$_NO_CHECKPOINT_DATA item code alsocancels a checkpoint in a print job so that the entire job isreprinted. By default, the BATCH$RESTART symbol is undefined.

(Valid for SJC$_ALTER_JOB function code)

SJC$_CLI

SJC$_NO_CLI

The SJC$_CLI item code is an input value item code. It is meaningfulonly for batch jobs. It specifies that the command language interpreterto be executed is SYS$SYSTEM:name.EXE, where name is a validOpenVMS RMS file name. The buffer must specify a name string from 1 to39 characters.

The SJC$_NO_CLI item code is a Boolean item code. It specifies that thecommand language interpreter to be executed is the one specified in theuser authorization file. It is the default.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_CLOSE_QUEUE

The SJC$_CLOSE_QUEUE item code is a Boolean item code. It specifiesthat jobs cannot be entered in the queue. If the queue is closed, youcan specify the SJC$_OPEN_QUEUE item code to permit jobs to be enteredin the queue. By default, the queue is open.

Whether a queue is open or closed is independent of any other queuestates (such as paused, stalled, stopped).

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_CPU_DEFAULT

SJC$_NO_CPU_DEFAULT

The SJC$_CPU_DEFAULT item code is an input value item code. It ismeaningful only for batch execution queues. It specifies the defaultCPU time limit in 10-millisecond units. The buffer contains thislongword value. The value 0 specifies unlimited CPU time. You canspecify a value that represents up to 497 days of CPU time.

The SJC$_NO_CPU_DEFAULT item code is a Boolean item code. It ismeaningful only for batch execution queues. It specifies that nodefault CPU time limit is to apply to the job. It is the default.

A CPU time limit for the process is included in each user record in thesystem user authorization file (UAF). You can also specify any or allof the following: a CPU time limit for individual jobs, a default CPUtime limit for all jobs in a given queue, and a maximum CPU time limitfor all jobs in a given queue. Table SYS-54 shows the action takenwhen you specify a value for SJC$_CPU_DEFAULT.

Table SYS-54 CPU Time Limit Decision Table

CPU Time Limit Specified for Job?	Default CPU Time Limit Specified for Queue?	Maximum CPU Time Specified for Queue?	Action Taken
No	No	No	Use UAF value
Yes	No	No	Use smaller of job's limit and UAF value
Yes	Yes	No	Use smaller of job's limit and UAF value
Yes	No	Yes	Use smaller of job's limit and maximum
Yes	Yes	Yes	Use smaller of job's limit and maximum
No	Yes	Yes	Use smaller of queue's default and maximum
No	No	Yes	Use maximum
No	Yes	No	Use smaller of UAF value and queue's default

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_CPU_LIMIT

SJC$_NO_CPU_LIMIT

The SJC$_CPU_LIMIT item code is an input value item code. It ismeaningful only for batch execution queues and batch jobs. It specifiesthe maximum CPU time limit for batch jobs in 10-millisecond units. Thebuffer must contain this longword value. The value 0 specifiesunlimited CPU time. You can specify a value that represents up to 497days of CPU time.

The SJC$_NO_CPU_LIMIT item code is a Boolean item code. It ismeaningful only for batch execution queues and batch jobs. It specifiesthat no maximum CPU time limit is to apply to the job. It is thedefault.

For information about the action taken when you specify a value forSJC$_CPU_LIMIT, refer to the description of the SJC$_CPU_DEFAULT itemcode and to Table SYS-54.

(Valid for SJC$_ALTER_JOB, SJC$_ALTER_QUEUE, SJC$_CREATE_JOB,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE function codes)

SJC$_CREATE_START

Boolean item code. It specifies that a queue be started after it iscreated. By default, a queue remains stopped after it is created.

(Valid for SJC$_CREATE_QUEUE function code)

SJC$_DEFAULT_FORM_NAME

SJC$_DEFAULT_FORM_NUMBER

The SJC$_DEFAULT_FORM_NAME and SJC$_DEFAULT_FORM_NUMBER item codes areinput value item codes. They specify the default form for a specificoutput queue by name and by number, respectively.

When you specify a default form for an output queue, the queue uses thequeue-specific default form, rather than the systemwide default form,to process any job that does not explicitly specify a form.

For SJC$_DEFAULT_FORM_NAME, the buffer must specify a form name. Thestring can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the number oftranslations allowed by the system has been performed. The maximumlength of the final character string is 31 characters; spaces, tabs,and null characters are ignored.

For SJC$_DEFAULT_FORM_NUMBER, the buffer must specify a longword value.You should use only one of these item codes to identify a default formfor the queue.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_DELETE_FILE

SJC$_NO_DELETE_FILE

The SJC$_DELETE_FILE item code is a Boolean item code. It specifiesthat a file should be deleted after the job completes. The file that isdeleted is the batch or print file submitted for execution. You cannotspecify this item code with the SJC$_ALTER_JOB function code, whichalters the parameters for an already existing job; you can make a filedeletion request only when a job is first submitted to the queue.

The SJC$_NO_DELETE_FILE item code is a Boolean item code. It specifiesthat a file should not be deleted after execution of the job. It is thedefault. You can specify this item code with the SJC$_ALTER_JOBfunction code; this makes it possible to cancel a file deletion requestthat was made when the job was first submitted to the queue.

(Valid for SJC$_ADD_FILE, SJC$_ENTER_FILE function codes)

SJC$_DESTINATION_QUEUE

Input value item code. When you specify the SJC$_ASSIGN_QUEUE functioncode, SJC$_DESTINATION_QUEUE specifies the name of the execution queueto which the logical queue is assigned. When you specify theSJC$_ABORT_JOB, SJC$_ALTER_JOB, or SJC$_MERGE_QUEUE function code,SJC$_DESTINATION_QUEUE specifies the name of the queue into which jobsare placed. By default, jobs remain in the original queue.

The string can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the number oftranslations allowed by the system has been performed. The maximumlength of the final character string is 31 characters; spaces, tabs,and null characters are ignored.

(Valid for SJC$_ABORT_JOB, SJC$_ALTER_JOB, SJC$_ASSIGN_QUEUE, andSJC$_MERGE_QUEUE function codes)

SJC$_DEVICE_NAME

Input value item code. It specifies the name of the device managed bythe output execution queue. The buffer must specify a string from 1 to255 characters. In an OpenVMS Cluster environment, theSJC$_SCSNODE_NAME item code is used to specify the name of the node onwhich the device is located.

This item code cannot be used with the SJC$_AUTOSTART_ON item code.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_DOUBLE_SPACE

SJC$_NO_DOUBLE_SPACE

The SJC$_DOUBLE_SPACE item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that thesymbiont should print the file with double spacing.

The SJC$_NO_DOUBLE_SPACE item code is a Boolean item code. It specifiesthat the symbiont should print the file with single spacing. It is thedefault.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_ENTRY_NUMBER

Input value item code. It specifies the entry number of the job onwhich to perform the function. The buffer must contain this entrynumber.

(Valid for SJC$_ABORT_JOB, SJC$_ALTER_JOB, SJC$_DELETE_JOB,SJC$_SYNCHRONIZE_JOB function codes)

SJC$_ENTRY_NUMBER_OUTPUT

Output value item code. The buffer must specify a longword into which$SNDJBC will write the entry number of a created job.

(Valid for SJC$_CREATE_JOB, SJC$_ENTER_FILE function codes)

SJC$_FILE_BURST

SJC$_FILE_BURST_ONE

SJC$_NO_FILE_BURST

The SJC$_FILE_BURST item code is a Boolean item code. It is meaningfulonly for output execution queues. It specifies that burst and flagpages are to be printed preceding a file. If you specifySJC$_FILE_BURST for a job, it specifies the default for all files inthe job; if you specify it for an output execution queue, it specifiesthe default for all jobs executed from that queue.

The SJC$_FILE_BURST_ONE item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that a burstpage is to be printed preceding a file. If you specifySJC$_FILE_BURST_ONE for a job, this item code specifies that a burstpage is to be printed preceding only the first copy of the first filein the job; if you specify SJC$_FILE_BURST_ONE for an output executionqueue, the item code specifies this behavior as the default for alljobs executed from that queue.

The SJC$_NO_FILE_BURST item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that no burstpage should be printed. It is the default.

(The following function codes are valid for SJC$_FILE_BURST item code:

SJC$_ADD_FILE
SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_ENTER_FILE
SJC$_START_QUEUE)

(The following function codes are valid for SJC$_FILE_BURST_ONE itemcode:

SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC_CREATE_QUEUE
SJC_START_QUEUE)

SJC$_FILE_COPIES

Input value item code. It is meaningful only for output executionqueues. It specifies the number of times a file is printed. By default,a file is repeated once. The buffer must specify a longword value from1 to 255; this value is the repeat count.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_FILE_FLAG

SJC$_FILE_FLAG_ONE

SJC$_NO_FILE_FLAG

The SJC$_FILE_FLAG item code is a Boolean item code. It is meaningfulonly for output execution queues. It specifies that a flag page is tobe printed preceding a file. If you specify SJC$_FILE_FLAG for a job,this item code indicates the default for all files in the job; if youspecify it for an output execution queue, SJC$_FILE_FLAG indicates thedefault for all jobs executed from that queue.

The SJC$_FILE_FLAG_ONE item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that a flagpage is to be printed preceding a file. If you specifySJC$_FILE_FLAG_ONE for a job, this item code specifies that a flag pageis to be printed preceding only the first copy of the first file in thejob; if you specify SJC$_FILE_FLAG_ONE for an output execution queue,it indicates this behavior as the default for all jobs executed fromthat queue.

The SJC$_NO_FILE_FLAG item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that no flagpage should be printed by default for jobs within the queue.

(The following function codes are valid for SJC$_FILE_FLAG item code:

SJC$_ADD_FILE
SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_ENTER_FILE
SJC$_START_QUEUE)

(The following function codes are valid for SJC$_FLAG_ONE item code:

SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_START_QUEUE)

SJC$_FILE_IDENTIFICATION

Input value item code. It specifies the file to be processed. Thebuffer contains a 28-byte value that identifies the file to beprocessed. This value specifies (in order) the following threefile-identification fields in the OpenVMS RMS NAM block: the 16-byteNAM$T_DVI field, the 6-byte NAM$W_FID field, and the 6-byte NAM$W_DIDfield. These fields occur consecutively in the NAM block.

If you specify SJC$_FILE_IDENTIFICATION, you must omit theSJC$_FILE_SPECIFICATION item code.

(Valid for SJC$_ADD_FILE, SJC$_ENTER_FILE function codes)

SJC$_FILE_SETUP_MODULES

SJC$_NO_FILE_SETUP_MODULES

The SJC$_FILE_SETUP_MODULES item code is an input value item code. Itis meaningful only for output execution queues. It specifies that alist of text modules should be extracted from the device controllibrary and copied to the printer before a file is printed. The buffermust contain a list of text module names, with a comma separating eachname.

The SJC$_NO_FILE_SETUP_MODULES item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that no textmodules should be copied before printing a file. It is the default.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_FILE_SPECIFICATION

Input value item code. It identifies the file to be processed. Thebuffer must contain the file specification of the file to be processed.The $SNDJBC service converts the file specification to thecorresponding file identification and proceeds as if theSJC$_FILE_IDENTIFICATION item code had been specified. If you specifySJC$_FILE_SPECIFICATION, you must omit the SJC$_FILE_IDENTIFICATIONitem code.

(Valid for SJC$_ADD_FILE, SJC$_ENTER_FILE function codes)

SJC$_FILE_TRAILER

SJC$_FILE_TRAILER_ONE

SJC$_NO_FILE_TRAILER

The SJC$_FILE_TRAILER item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that atrailer page is to be printed following a file. If you specifySJC$_FILE_TRAILER for a job, this item code indicates the default forall files in the job; if you specify it for an output execution queue,SJC$_FILE_TRAILER specifies the default for all jobs executed on thatqueue.

The SJC$_FILE_TRAILER_ONE item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that atrailer page is to be printed following a file. If you specifySJC$_FILE_TRAILER_ONE for a job, this item code indicates that atrailer page is to be printed following only the last copy of the lastfile in the job; if you specify it for an output execution queue,SJC$_FILE_TRAILER_ONE indicates this behavior as the default for alljobs executed on that queue.

The SJC$_NO_FILE_TRAILER item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that notrailer page should be printed. It is the default.

(The following function codes are valid for SJC$_FILE_TRAILER item code:

SJC$_ADD_FILE
SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_ENTER_FILE
SJC$_START_QUEUE)

(The following function codes are valid for SJC$_FILE_TRAILER_ONE itemcode:

SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_START_QUEUE)

SJC$_FIRST_PAGE

SJC$_NO_FIRST_PAGE

The SJC$_FIRST_PAGE item code is an input value item code. It ismeaningful only for jobs queued to output execution queues. Itspecifies the page number at which printing should begin. The buffermust contain a nonzero longword value specifying this page number.

The SJC$_NO_FIRST_PAGE item code is a Boolean item code. It ismeaningful only for jobs queued to output execution queues. Itspecifies that printing should begin with the first page. It is thedefault.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_FORM_DESCRIPTION

Input value item code. It provides operator-supplied informationdescribing the form. By default, the form name is used. The buffer mustspecify a string of no more than 255 characters.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_LENGTH

Input value item code. It specifies the physical length of the form inlines. The buffer must contain a nonzero longword integer value. Bydefault, the form length is 66 lines.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_MARGIN_BOTTOM

Input value item code. It specifies the bottom margin of the form inlines. By default, the bottom margin is 6 lines.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_MARGIN_LEFT

Input value item code. It specifies the width of the left margin of theform in characters. By default, the left margin is 0. The buffer mustspecify a longword value.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_MARGIN_RIGHT

Input value item code. It specifies the width of the right margin ofthe form in characters. By default, the right margin is 0. The buffermust specify a longword value.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_MARGIN_TOP

Input value item code. It specifies the top margin of the form inlines. By default, the top margin is 0.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_NAME

SJC$_FORM_NUMBER

The SJC$_FORM_NAME and SJC$_FORM_NUMBER item codes are input value itemcodes. They specify a mounted form for the queue by name and by number,respectively. For SJC$_FORM_NAME, the buffer must specify a form name.For SJC$_FORM_NUMBER, the buffer must specify a longword value. Youshould use only one of these two item codes to identify a form in queueand job related function codes.

The SJC$_DEFINE_FORM and SJC$_DELETE_FORM function codes include anddelete, respectively, a specified form name and number from the systemjob queue file. The mounted form indicates the stock type of the outputqueue. A job cannot execute on an output queue unless the stock type ofthe form specified (by name or number) for the job item code is thesame as the stock type of the mounted form specified for the queue. Formore information about how the stock type of a form affects jobprocessing, refer to the HP OpenVMS System Manager's Manual.

The string can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the number oftranslations allowed by the system has been performed. The maximumlength of the final character string is 31 characters; spaces, tabs,and null characters are ignored.

(The following function codes are valid for SJC$_FORM_NAME item code:

SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_DEFINE_FORM
SJC$_DELETE_FORM
SJC$_ENTER_FILE
SJC$_START_QUEUE)

(The following function codes are valid for SJC$_FORM_NUMBER item code:

SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_DEFINE_FORM
SJC$_ENTER_FILE
SJC$_START_QUEUE)

SJC$_FORM_SETUP_MODULES

SJC$_NO_FORM_SETUP_MODULES

The SJC$_FORM_SETUP_MODULES item code is an input value item code. Thebuffer must specify one or more text module names, with a commaseparating each name. This item code specifies that these modulesshould be extracted from the device control library and copied to theprinter before each file that is printed on the form.

The SJC$_NO_FORM_SETUP_MODULES item code is a Boolean item code. Itspecifies that no device control modules should be copied. It is thedefault.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_SHEET_FEED

SJC$_NO_FORM_SHEET_FEED

The SJC$_FORM_SHEET_FEED item code is a Boolean item code. It specifiesthat the symbiont should pause at the end of each physical page so thata new sheet can be inserted.

The SJC$_NO_FORM_SHEET_FEED item code is a Boolean item code. Itspecifies that the output symbiont should not pause at the end of everyphysical page. It is the default.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_STOCK

Input value item code. It specifies a name for the paper stock. Thebuffer must contain a string of 1 to 31 characters. By default, thename of the paper stock is the form name.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_TRUNCATE

SJC$_NO_FORM_TRUNCATE

The SJC$_FORM_TRUNCATE item code is a Boolean item code. It specifiesthat the symbiont should truncate lines that extend beyond the rightmargin. Specifying SJC$_FORM_TRUNCATE cancels SJC$_FORM_WRAP. TheSJC$_FORM_TRUNCATE item code is the default.

The SJC$_NO_FORM_TRUNCATE item code is a Boolean item code. Itspecifies that the output symbiont should not truncate lines thatextend beyond the right margin.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_WIDTH

Input value item code. It specifies the physical width of the form incharacters. The buffer must contain a nonzero longword integer. Bydefault, the form width is 132 characters.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_FORM_WRAP

SJC$_NO_FORM_WRAP

The SJC$_FORM_WRAP item code is a Boolean item code. It specifies thatthe symbiont should wrap lines that extend beyond the right margin.Specifying SJC$_FORM_WRAP cancels SJC$_FORM_TRUNCATE.

The SJC$_NO_FORM_WRAP item code is a Boolean item code. It specifiesthat the output symbiont should not wrap lines. It is the default.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_GENERIC_QUEUE

SJC$_NO_GENERIC_QUEUE

The SJC$_GENERIC_QUEUE item code is a Boolean item code. It specifiesthat a queue is a generic queue.

The SJC$_NO_GENERIC_QUEUE item code is a Boolean item code. Itspecifies that a queue is not a generic queue. It is the default. Bydefault, a queue is an execution queue; see the Description section fora full discussion of the types of queue.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_GENERIC_SELECTION

SJC$_NO_GENERIC_SELECTION

The SJC$_GENERIC_SELECTION item code is a Boolean item code. Itspecifies that an execution queue can accept jobs from a generic queue.It is the default. It is meaningful only for execution queues.

The SJC$_NO_GENERIC_SELECTION item code is a Boolean item code. Itspecifies that an execution queue cannot accept jobs from a genericqueue.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_GENERIC_TARGET

Input value item code. The buffer must specify a queue name. This queuename identifies an execution queue that can accept jobs from a genericqueue. This item code is meaningful only for generic queues.

This item code can appear up to 124 times in a single call to $SNDJBC.The set of queues defined in a single call completely replaces the setdefined by a prior call.

The string can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the number oftranslations allowed by the system has been performed. The maximumlength of the final character string is 31 characters; spaces, tabs,and null characters are ignored.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_HOLD

SJC$_NO_HOLD

The SJC$_HOLD item code is a Boolean item code. It specifies that a jobcannot execute and must enter a holding status.

The SJC$_NO_HOLD item code is a Boolean item code. It specifies that ajob can execute immediately when used with the SJC$_ALTER_JOB functioncode. It makes the following types of job eligible for execution: (1) ajob that is holding because it was specified with the SJC$_HOLD itemcode, (2) a job that was refused by the symbiont, and (3) a job thatwas retained after execution. It is the default. SJC$_NO_HOLD does notrelease a job that is specified with the SJC$_AFTER_TIME item code.

(Valid for SJC$_ABORT_JOB, SJC$_ALTER_JOB, SJC$_CREATE_JOB,SJC$_ENTER_FILE function codes)

SJC$_JOB_BURST

SJC$_NO_JOB_BURST

The SJC$_JOB_BURST item code is a Boolean item code. It specifies thatburst and flag pages are to be printed preceding each job. It ismeaningful only for output execution queues.

The SJC$_NO_JOB_BURST item code is a Boolean item code. It specifiesthat a burst page is not to be printed preceding each job. It ismeaningful only for output execution queues. It is the default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_COMPLETION_STATUS

Output item code. Use this item code to receive the completion statusof the job being synchronized.

You can omit the IOSB in the $SNDJBC call and receive the completionstatus in this item's value.

(Valid for the SJC$_SYNCHRONIZE_JOB function code)

SJC$_JOB_COPIES

Input value item code. It specifies the number of times that the entireprint job is to be repeated. The buffer must contain this nonzerolongword integer value. By default, the print job is repeated once.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_JOB_DEFAULT_RETAIN

Boolean item code. It specifies that you want the job to be held in thequeue as specified by the queue's retention policy.

For more information about user-specified job retention, see the/RETAIN qualifier for the PRINT or SUBMIT command in the HP OpenVMS DCL Dictionary.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_JOB_ERROR_RETAIN

Boolean item code. It specifies that you want the job to be retained inthe queue if the job completes unsuccessfully. However, the job mightbe held in the queue even if it completes successfully if the queue isset to retain all jobs because the QUI$V_QUEUE_RETAIN_ALL bit is set inthe QUI$_QUEUE_FLAGS item code.

For more information about user-specified job retention, see the/RETAIN qualifier for the PRINT or SUBMIT command in the HP OpenVMS DCL Dictionary.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SCJ$_ENTER_FILE functioncodes)

SJC$_JOB_FLAG

SJC$_NO_JOB_FLAG

The SJC$_JOB_FLAG item code is a Boolean item code. It specifies that aflag page is to be printed preceding each job. It is meaningful onlyfor output execution queues.

The SJC$_NO_JOB_FLAG item code is a Boolean item code. It specifiesthat a flag page is not to be printed preceding each job. It ismeaningful only for output execution queues. It is the default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_LIMIT

Input value item code. It specifies the maximum number of jobs that canexecute simultaneously on a queue. The buffer must contain a longwordvalue in the range 1 to 255. It is meaningful only for batch executionqueues. By default, the job limit is 1.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_NAME

Input value item code. It specifies the name of a job. The buffer mustspecify a string from 1 to 39 characters.

For function codes SJC$_ENTER_FILE, SJC$_CREATE_JOB, andSJC$_ALTER_JOB, SJC$_JOB_NAME specifies the identifying name of thejob. By default, the name used is the name of the first file in the job.

For function code SJC$_SYNCHRONIZE_JOB, SJC$_JOB_NAME specifies thename of the job on which to operate. The job name is implicitlyqualified by the user name.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE,SJC$_SYNCHRONIZE_JOB function codes)

SJC$_JOB_RESET_MODULES

SJC$_NO_JOB_RESET_MODULES

The SJC$_JOB_RESET_MODULES item code is an input value item code. It ismeaningful only for output execution queues. The buffer must specifythe names of one or more text modules, with a comma separating eachname. This item code specifies that these modules are to be extractedfrom the device control library and copied to the printer before eachprint job.

The SJC$_NO_JOB_RESET_MODULES item code is a Boolean item code. Itspecifies that no text modules should be copied to the printer. It isthe default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_RETAIN

Boolean item code. It specifies that you want the job to be retained inthe queue after it has executed, regardless of the job's completionstatus.

For more information about user-specified job retention, see the/RETAIN qualifier for the PRINT or SUBMIT command in the HP OpenVMS DCL Dictionary.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_JOB_RETAIN_TIME

Input value item code. It specifies a quadword time value representingthe length of time you want the job to be retained in the queue.

If a delta time is provided, the delta begins when the job completes;however, depending on the queue's job retention policy, the job mightbe retained indefinitely.

For more information about user-specified job retention, refer to the/RETAIN qualifier for the PRINT or SUBMIT command in the HP OpenVMS DCL Dictionary.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_JOB_SIZE_MAXIMUM

SJC$_NO_JOB_SIZE_MAXIMUM

The SJC$_JOB_SIZE_MAXIMUM item code is an input value item code. It ismeaningful only for output execution queues. It specifies that a printjob can execute only if its total size in blocks is less than or equalto the specified value. The buffer specifies this nonzero longwordvalue.

The SJC$_NO_JOB_SIZE_MAXIMUM item code is a Boolean item code. Itspecifies that a print job can execute immediately regardless of itssize. It is the default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_SIZE_MINIMUM

SJC$_NO_JOB_SIZE_MINIMUM

The SJC$_JOB_SIZE_MINIMUM item code is an input value item code. It ismeaningful only for output execution queues. It specifies that a printjob can execute only if its total size in blocks is greater than orequal to the specified value. The buffer specifies this nonzerolongword value.

The SJC$_NO_JOB_SIZE_MINIMUM item code is a Boolean item code. Itspecifies that a print job can execute immediately regardless of itssize. It is the default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_SIZE_SCHEDULING

SJC$_NO_JOB_SIZE_SCHEDULING

The SJC$_JOB_SIZE_SCHEDULING item code is a Boolean item code. Itspecifies that print jobs entered in an output queue should bescheduled according to size, with the smallest job of a given priorityprocessed first. It is the default.

The SJC$_NO_JOB_SIZE_SCHEDULING item code is a Boolean item code. Itspecifies that print jobs of a given priority should not be scheduledaccording to print size.

Changing the value of this item code for a queue while print jobs arepending on any queue produces unpredictable results.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_JOB_STATUS_OUTPUT

Output value item code. When specified, $SNDJBC returns, as a characterstring, a textual message describing the status of a submitted job.Because the message can include up to 255 characters, the buffer lengthfield of the item descriptor should specify 255 (bytes).

(Valid for SJC$_CLOSE_JOB, SJC$_ENTER_FILE function codes)

SJC$_JOB_TRAILER

SJC$_NO_JOB_TRAILER

The SJC$_JOB_TRAILER item code is a Boolean item code. It is meaningfulonly for output execution queues. It specifies that a trailer page isto be printed following each job.

The SJC$_NO_JOB_TRAILER item code is a Boolean item code. It ismeaningful only for output execution queues. It specifies that atrailer page is not to be printed following each job. It is the default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_LAST_PAGE

SJC$_NO_LAST_PAGE

The SJC$_LAST_PAGE item code is an input value item code. It ismeaningful only for jobs submitted to output execution queues. Itspecifies the page number at which printing should end. The bufferspecifies this nonzero longword value.

The SJC$_NO_LAST_PAGE item code is a Boolean item code. It specifiesthat printing should end after the last page. It is the default.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_LIBRARY_SPECIFICATION

SJC$_NO_LIBRARY_SPECIFICATION

The SJC$_LIBRARY_SPECIFICATION item code is an input value item code.It is meaningful only for output execution queues. It specifies thatthe device control library for the queue is SYS$LIBRARY:name.TLB, wherename is a valid RMS file name. The buffer must specify theOpenVMS RMS file name.

The SJC$_NO_LIBRARY_SPECIFICATION item code is a Boolean item code. Itspecifies that the device control library is SYS$LIBRARY:SYSDEVCTL.TLB.It is the default.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_LOG_DELETE

SJC$_NO_LOG_DELETE

The SJC$_LOG_DELETE item code is a Boolean item code. It specifies thatthe log file produced for a batch job is to be deleted. It ismeaningful only for batch jobs. It is the default.

The SJC$_NO_LOG_DELETE item code is a Boolean item code. It specifiesthat the log file produced for a batch job is not to be deleted.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_LOG_QUEUE

Input value item code. It is meaningful only for batch jobs. Itspecifies the queue into which the log file produced for the batch jobis entered for printing. The buffer must specify the name of the queue.By default, the log file is entered in queue SYS$PRINT.

The string can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the number oftranslations allowed by the system has been performed. The maximumlength of the final character string is 31 characters; spaces, tabs,and null characters are ignored.

If your system uses multiple queue managers to run batch queues on aseparate queue manager from output queues, certain checks that wouldotherwise be performed for the SJC$_LOG_QUEUE item code of the $SNDJBCsystem service are not performed.

When batch and print queues are managed by the same queue manager, thequeue manager checks to ensure that the queue specified with theSJC$_LOG_QUEUE is an output queue and that the user has access to theoutput queue. These checks are not made if the batch queue specified bythe $SNDJBC service and the output queue specified by theSJC$_LOG_QUEUE item code are managed by different queue managers. Ifyou explicitly specify an output queue for the log file when submittinga batch job, be sure the queue you specify with the SJC$_LOG_QUEUE isan output queue and not a batch queue. Also, be sure that you haveaccess to the printer queue.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_LOG_SPECIFICATION

SJC$_NO_LOG_SPECIFICATION

The SJC$_LOG_SPECIFICATION item code is an input value item code. It ismeaningful only for batch jobs. It specifies the file specification ofthe log file produced for a batch job. The buffer must contain thisOpenVMS RMS file specification. Omitted fields in the filespecification are supplied from the default file specificationSYS$LOGIN:name.LOG, where name is the job name. By default alog file is produced using this default file specification to generatethe log file name.

The SJC$_NO_LOG_SPECIFICATION item code is a Boolean item code. Itspecifies that no log file should be produced for the batch job.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_LOG_SPOOL

SJC$_NO_LOG_SPOOL

The SJC$_LOG_SPOOL item code is a Boolean item code. It specifies thatthe log file produced for a batch job is to be printed. It ismeaningful only for batch jobs. It is the default.

The SJC$_NO_LOG_SPOOL item code is a Boolean item code. It specifiesthat the log file for a batch job is not to be printed.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_LOWERCASE

SJC$_NO_LOWERCASE

The SJC$_LOWERCASE item code is a Boolean item code. It specifies thata job can execute only on a device that has the LOWERCASEdevice-dependent characteristic. It is meaningful only for jobssubmitted to output execution queues.

The SJC$_NO_LOWERCASE item code is a Boolean item code. It specifiesthat a job can execute whether or not the output device has theLOWERCASE device-dependent characteristic. It is the default.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_NEW_VERSION

Boolean item code. When used with the SJC$_START_QUEUE_MANAGER functioncode, it specifies that a new (empty) version of the queue database isto be created, whether or not the database files already exist.

This item code is required when initially creating and starting thequeuing system, but it should be used with caution thereafter.

Caution If you specify this item code and a queue database already exists, thenew master and queue files of the queue database supersede existingversion of those files; however, the journal files of the queuedatabase are deleted. Thus, jobs and other information are lost. When used with the SJC$_START_ACCOUNTING function code, theSJC$_NEW_VERSION item code specifies that a new version of the systemaccounting file is to be created, whether or not the file alreadyexists.

(Valid for SJC$_START_ACCOUNTING, SJC$_START_QUEUE_MANAGER functioncodes)

SJC$_NEXT_JOB

Boolean item code. It is meaningful only for paused output executionqueues. It specifies that the current job should be aborted and thatprinting should be resumed with the next job.

(Valid for SJC$_START_QUEUE function code)

SJC$_NOTE

SJC$_NO_NOTE

The SJC$_NOTE item code is an input value item code. It is meaningfulfor batch and output execution queues. It specifies a string to beprinted on the job flag and file flag pages. The buffer must specifythis string.

The SJC$_NO_NOTE item code is a Boolean item code. It specifies that nostring is to be printed on the job flag and file flag pages. It is thedefault.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_NOTIFY

SJC$_NO_NOTIFY

The SJC$_NOTIFY item code is a Boolean item code. It specifies that amessage is to be broadcast, at the time of job completion, to eachlogged-in terminal, of the user who submitted the job.

The SJC$_NO_NOTIFY item code is a Boolean item code. It specifies thatno message is to be broadcast at the time of job completion. It is thedefault.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_NO_RAD (Alpha only)

Boolean input item code. When the SJC$_NO_RAD code is specified in arequest, the RAD value for the queue or job is removed.

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

(Valid for SJC$_ALTER_JOB, SJC$_ALTER_QUEUE, SJC$_CREATE_JOB,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE)

SJC$_OPEN_QUEUE

Boolean item code. It specifies that jobs can be entered in the queue.To specify that jobs cannot be entered in the queue, use theSJC$_CLOSE_QUEUE item code. By default, the queue is open.

Whether a queue is open or closed is independent of any other queuestates (such as paused, stalled, stopped).

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_OPERATOR_REQUEST

SJC$_NO_OPERATOR_REQUEST

The SJC$_OPERATOR_REQUEST item code is an input value item code. It ismeaningful only for output execution queues. The buffer must contain atext string. This item code specifies that, when a job beginsexecution, the execution queue is to be placed in the paused state andthe specified text string is to be included in a message to the queueoperator requesting service.

The SJC$_NO_OPERATOR_REQUEST item code is a Boolean item code. Itspecifies that no message is to be sent to the queue operator. It isthe default.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_OWNER_UIC

Input value item code. It specifies the owner UIC of a queue. Thebuffer must specify the longword UIC. By default, the owner UIC is[1,4].

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_PAGE_HEADER

SJC$_NO_PAGE_HEADER

The SJC$_PAGE_HEADER item code is a Boolean item code. It is meaningfulonly for output execution queues. It specifies that a page heading isto be printed on each page of output.

The SJC$_NO_PAGE_HEADER item code is a Boolean item code. It specifiesthat no page heading is to be printed. It is the default.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_PAGE_SETUP_MODULES

SJC$_NO_PAGE_SETUP_MODULES

The SJC$_PAGE_SETUP_MODULES item code is an input value item code. Thebuffer must specify one or more text module names, with a commaseparating each name. This item code specifies that these modules areto be extracted from the device control library and copied to theprinter before each page is printed.

The SJC$_NO_PAGE_SETUP_MODULES item code is a Boolean item code. Itspecifies that no device control modules are to be copied. It is thedefault.

(Valid for SJC$_DEFINE_FORM function code)

SJC$_PAGINATE

SJC$_NO_PAGINATE

The SJC$_PAGINATE item code is a Boolean item code. It is meaningfulonly for output execution queues and jobs submitted to output executionqueues. It specifies that the symbiont should paginate the output byinserting a form feed whenever output reaches the bottom margin of theform. It is the default.

The SJC$_NO_PAGINATE item code is a Boolean item code. It specifiesthat the symbiont should not paginate the output.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ALTER_QUEUE,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE function codes)

SJC$_PARAMETER_1 through SJC$_PARAMETER_8

SJC$_NO_PARAMETERS

The SJC$_PARAMETER_1 through SJC$_PARAMETER_8 item codes are inputvalue item codes; the last digit of the item code name is a number from1 through 8. For each item code specified, the buffer must specify astring of no more than 255 characters. For batch jobs, the stringbecomes the value of the DCL symbol P1 through P8, respectively, withinthe outermost command procedure.

For print jobs, the system makes the string available to the symbiont,though the standard OpenVMS print symbiont does not use thisinformation. By default, each of the eight parameters specifies a nullstring.

For function code SJC$_ALTER_JOB, if any SJC$_PARAMETER item isspecified, the value of each unspecified item is the null string.

The SJC$_NO_PARAMETERS item code is a Boolean item code. It specifiesthat none of the SJC$_PARAMETER items are to be passed in the batch orprint job. It is the default.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_PASSALL

SJC$_NO_PASSALL

The SJC$_PASSALL item code is a Boolean item code. It is meaningfulonly for jobs submitted to output execution queues. It specifies thatthe symbiont is to print the file in PASSALL mode.

The SJC$_NO_PASSALL item code is a Boolean item code. It specifies thatthe symbiont is not to print the file in PASSALL mode. It is thedefault.

(Valid for SJC$_ADD_FILE, SJC$_ALTER_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_PRINTER

Boolean item code. It is meaningful only for output queues. Itspecifies that the queue being created is a printer queue. TheSJC$_BATCH, SJC$_PRINTER, SJC$_SERVER, and SJC$_TERMINAL item codes aremutually exclusive. If none of these item codes are specified, thedefault is SJC$_PRINTER.

(Valid for SJC$_CREATE_QUEUE function code)

SJC$_PRIORITY

Input value item code. The buffer must specify a longword value in therange 0 through 255. This value specifies the scheduling priority ofthe job in a queue relative to the scheduling priority of other jobs inthe same queue.

By default, the scheduling priority of the job is the value of thesystem parameter DEFQUEPRI.

If you specify a value for SJC$_PRIORITY that is greater than thesystem parameter MAXQUEPRI and you do not have either ALTPRI or OPERprivilege, the system uses the greater of the following two values:DEFQUEPRI or MAXQUEPRI. If you have either ALTPRI or OPER privilege,the system uses any value you specify for SJC$_PRIORITY, even if it isincluded in the range between MAXQUEPRI + 1 and 255.

(Valid for SJC$_ABORT_JOB, SJC$_ALTER_JOB, SJC$_CREATE_JOB,SJC$_ENTER_FILE function codes)

SJC$_PROCESSOR

SJC$_NO_PROCESSOR

The SJC$_PROCESSOR item code is an input value item code. The buffermust specify a valid OpenVMS RMS file name.

When specified for an output execution queue, SJC$_PROCESSOR specifiesthat the symbiont image to be executed is SYS$SYSTEM:name.EXE, wherename is the RMS file name contained in the buffer.

When specified for a generic output queue, SJC$_PROCESSOR specifiesthat the generic queue can place jobs only in server queues that areexecuting the symbiont image SYS$SYSTEM:name.EXE, where nameis the RMS file name contained in the buffer.

The SJC$_NO_PROCESSOR item code is a Boolean item code. It specifiesthat the symbiont image to be executed is SYS$SYSTEM:PRTSMB.EXE. It isthe default.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_PROTECTION

Input value item code. It specifies the protection of a queue.

The buffer must specify a longword in the format shown in the followingdiagram:

Bits 0 through 15 specify the protection value: the four types ofaccess (read, submit, manage, delete) to be granted to the fourcategories of user (System, Owner, Group, World). Set bits deny accessand clear bits allow access.

Bits 16 through 31 specify the protection enable mask: they identifywhich part of the protection value (bits 0 through 15) is to be appliedto queue protection. If all bits are set in the enable mask, it meansthat all of the protection values are to be applied. A value other than--1 in the protection enable mask means that only those bits set willaffect the corresponding bits in the protection value. When a bit inthe protection enable mask is clear, the corresponding bit in theexisting queue protection value is unchanged.

By default, the queue protection is (S:M,O:D,G:R,W:S).

Note that on VAX systems you can assign ACLs to queues using the$SET_SECURITY system service.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_QUEUE

The string can contain uppercase or lowercase characters (lowercase areconverted to uppercase), numeric characters, dollar signs ($), andunderscores (_). If the string is a logical name, SYS$SNDJBC translatesit iteratively until the equivalence string is found or the maximumnumber of translations allowed by the system has been performed. Themaximum length of the final character string is 31 characters; spaces,tabs, and null characters are ignored.

(The following function codes are valid for SJC$_QUEUE item code:

SJC$_ABORT_JOB
SJC$_ALTER_JOB
SJC$_ALTER_QUEUE
SJC$_CREATE_JOB
SJC$_CREATE_QUEUE
SJC$_DELETE_JOB
SJC$_DELETE_QUEUE
SJC$_ENTER_FILE
SJC$_START_QUEUE
SJC$_SYNCHRONIZE_JOB)

SJC$_QUEUE_DESCRIPTION

SJC$_NO_QUEUE_DESCRIPTION

The SJC$_NO_QUEUE_DESCRIPTION item code is a Boolean item code. Itspecifies that no description is associated with the queue.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_QUEUE_DIRECTORY

The default location of the queue and journal files isSYS$COMMON:[SYSEXE]. The optional use of SJC$_QUEUE_DIRECTORY is forspecifying an alternate location for the queue and journal files. Thespecification must include at least the device and directory name;wildcard characters are not allowed in the directory specification. Thedirectory specified must be available to all nodes that can run thequeue manager. If the directory specification is a concealed logicalname, it must be defined identically on all nodes in the cluster.

The location of the queue and journal files is stored in the masterfile of the queue database. You do not have to respecify the directorylocation with subsequent use of SJC$_START_QUEUE_MANAGER.

For more information, refer to the HP OpenVMS System Manager's Manual.

(Valid for SJC$_START_QUEUE_MANAGER function code)

SJC$_QUEUE_MANAGER_NAME

The maximum length of the final character string is 31 characters. Aswith queue names, this can be a logical and will be resolved by thesystem. Once resolved, the name provided will serve as the file namefor the queue and journal files, the process name, and the user namefor the active process. Only the first 15 and 12 characters of the nameare used for the process and user names, respectively.

(Valid for SJC$_CREATE_QUEUE, SJC$_DELETE_QUEUE_MANAGER,SJC$_DISABLE_AUTOSTART, SJC$_ENABLE_AUTOSTART,SJC$_START_QUEUE_MANAGER, SJC$_STOP_ALL_QUEUES_ON_NODE,SJC$_STOP_QUEUE_MANAGER function codes)

SJC$_QUEUE_MANAGER_NODES

The default value for the node list is an asterisk (*); it specifiesthat all nodes in the cluster are eligible to run the queue manager.The asterisk can also be specified as an element of the list. Forexample, a list can be specified as nodes A, B, C, *. If the node onwhich the queue manager is running leaves the cluster, the queuemanager automatically fails over to any available node in the cluster;that is, if nodes A, B, and C are unavailable, then the queue managercan run on any other node. When establishing the node list, there is novalidation of the individual nodes. If, for example, a node name ismisspelled, there is no error status returned.

Anytime the SJC$_START_QUEUE_MANAGER function code is used, the jobcontroller checks the queue database to see if the node list is otherthan the default (*). If the node list is other than the default andthe queue manager is running on a node other than the first availablenode of those specified, then the queue manager process is moved fromits current node and restarted on the first available preferred node.When a current call includes the SJC$_QUEUE_MANAGER_NODES item code,the job controller also updates the node list stored in the database.Despite this transition, queues on the running nodes are not stopped,and all requests to the queuing system complete as expected.

Note that because the specified node list is saved in the database, itis used every time the SJC$_START_QUEUE_MANAGER function code is used,unless the node list has been changed by a more recent call to $SNDJBCwith the SJC_$QUEUE_MANAGER_NODES item code.

For more information, refer to the HP OpenVMS System Manager's Manual.

(Valid for SJC$_START_QUEUE_MANAGER function code)

SJC$_RAD (Alpha only)

Note: OpenVMS support for RADs is available only on the AlphaServer GS series systems. For more information about using RADs, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.

(Valid for SJC$_ALTER_JOB, SJC$_ALTER_QUEUE, SJC$_CREATE_JOB,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE)

SJC$_RECORD_BLOCKING

SJC$_NO_RECORD_BLOCKING

The SJC$_NO_RECORD_BLOCKING item code is a Boolean item code. Itspecifies that the symbiont must send each record in a separate I/Orequest to the output device.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_RELATIVE_PAGE

(Valid for SJC$_START_QUEUE function code)

SJC$_REQUEUE

(Valid for SJC$_ABORT_JOB function code)

SJC$_RESTART

SJC$_NO_RESTART

The SJC$_NO_RESTART item code is a Boolean item code. It specifies thata job cannot restart after a system failure or after a requeueoperation. It is the default for batch jobs.

(Valid for SJC$_ALTER_JOB, SJC$_CREATE_JOB, SJC$_ENTER_FILE functioncodes)

SJC$_RETAIN_ALL_JOBS

SJC$_RETAIN_ERROR_JOBS

SJC$_NO_RETAIN_JOBS

The SJC$_RETAIN_ERROR_JOBS item code is a Boolean item code. Itspecifies that jobs are to be retained only if the job completedunsuccessfully (the job's completion status has the low bit clear).

The SJC$_NO_RETAIN_JOBS item code is a Boolean item code. It specifiesthat jobs are not to be retained in the queue after they havecompleted. It is the default.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_SCSNODE_NAME

When used with the function codes of SJC$_STOP_ALL_QUEUES_ON_NODE,SJC$_DISABLE_AUTOSTART, and SJC$_ENABLE_AUTOSTART, this item coderequests a function on a node other than the node from which the$SNDJBC request is sent.

SJC$_SCSNODE_NAME is meaningful only for execution queues in a clusterenvironment. By default, the queue executes on the node from which thequeue is first started. For an output execution queue, you use theSJC$_DEVICE_NAME item code to specify the name of the device managed bythe queue.

(Valid for SJC$_CREATE_QUEUE, SJC$_DISABLE_AUTOSTART,SJC$_ENABLE_AUTOSTART, SJC$_START_QUEUE, SJC$_STOP_ALL_QUEUES_ON_NODEfunction codes)

SJC$_SEARCH_STRING

(Valid for SJC$_START_QUEUE function code)

SJC$_SERVER

The SJC$_BATCH, SJC$_PRINTER, SJC$_SERVER, and SJC$_TERMINAL item codesare mutually exclusive. If none of these item codes are specified, thedefault is SJC$_PRINTER.

(Valid for SJC$_CREATE_QUEUE function code)

SJC$_SWAP

SJC$_NO_SWAP

The SJC$_NO_SWAP item code is a Boolean item code. It specifies thatjobs in this queue cannot be swapped.

(Valid for SJC$_ALTER_QUEUE, SJC$_CREATE_QUEUE, SJC$_START_QUEUEfunction codes)

SJC$_TERMINAL

SJC$_NO_TERMINAL

The SJC$_BATCH, SJC$_PRINTER, SJC$_SERVER, and SJC$_TERMINAL item codesare mutually exclusive. If none of these item codes are specified, thedefault is SJC$_PRINTER.

The SJC$_NO_TERMINAL item code is a Boolean item code. It designatesthe queue type as printer rather than terminal. It is the default.

For the SJC$_START_QUEUE function code, SJC$_TERMINAL andSJC$_NO_TERMINAL are supported for compatibility with VAX VMS Version4.n, but might not be supported in the future. For SJC$_CREATE_QUEUE,SJC$_NO_TERMINAL is supported for compatibility with VAX VMS Version4.n, and might not be supported in the future.

(Valid for SJC$_CREATE_QUEUE, SJC$_START_QUEUE function codes)

SJC$_TOP_OF_FILE

(Valid for SJC$_START_QUEUE function code)

SJC$_UIC

(Valid for SJC$_CREATE_JOB, SJC$_ENTER_FILE function codes)

SJC$_USERNAME

You need CMKRNL privilege to use this item code.

(Valid for SJC$_CREATE_JOB, SJC$_ENTER_FILE function codes)

SJC$_WSDEFAULT

SJC$_NO_WSDEFAULT

The SJC$_NO_WSDEFAULT item code is a Boolean item code. It specifiesthat the system is to determine the working set default. It is thedefault.

For batch jobs, the default working set size, working set quota, andworking set extent (maximum size) are included in each user record inthe system user authorization file (UAF). You can specify values forthese items for individual jobs or for all jobs in a given queue, orfor both. Table SYS-55 shows the action taken when you specify a valuefor SJC$_WSDEFAULT.

(Valid for SJC$_ALTER_JOB, SJC$_ALTER_QUEUE, SJC$_CREATE_JOB,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE function codes)

SJC$_WSEXTENT

SJC$_NO_WSEXTENT

The SJC$_NO_WSEXTENT item code is a Boolean item code. It specifiesthat the system determine the working set extent. It is the default.

For information about the action taken when you specify a value forSJC$_WSEXTENT for a batch job or batch queue, refer to the descriptionof the SJC$_WSDEFAULT item code and to Table SYS-55.

(Valid for SJC$_ALTER_JOB, SJC$_ALTER_QUEUE, SJC$_CREATE_JOB,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE function codes)

SJC$_WSQUOTA

SJC$_NO_WSQUOTA

The SJC$_NO_WSQUOTA item code is a Boolean item code. It specifies thatthe system is to determine the working set quota. It is the default.

For information about the action taken when you specify a value forSJC$_WSQUOTA for a batch job or batch queue, refer to the descriptionof the SJC$_WSDEFAULT item code and to Table SYS-55.

(Valid for SJC$_ALTER_JOB, SJC$_ALTER_QUEUE, SJC$_CREATE_JOB,SJC$_CREATE_QUEUE, SJC$_ENTER_FILE, SJC$_START_QUEUE function codes)

Description

The Send to Job Controller service creates, stops, and manages queuesand the batch and print jobs in those queues. The $SNDJBC and $GETQUI(Get Queue Information) services together provide the user interface tothe queue manager and job controller processes. See the description ofthe $GETQUI service for a discussion of queues and jobs initiated fromthose queues.

$SNDJBC completes asynchronously; that is, it returns to the callerafter queuing the request, without waiting for the operation tocomplete.

To synchronize the completion of most operations, you use the Send toJob Controller and Wait ($SNDJBCW) service. The $SNDJBCW service isidentical to $SNDJBC in every way except that $SNDJBCW returns to thecaller after the operation completes.

Types of Queues

The VMS batch and print queuing system supports several types ofqueues, which aid in the processing of batch and print jobs. Thedifferent types of queues can be divided into three major categoriesaccording to the way the system processes the jobs assigned to thequeue. The three types of queues are execution, generic, and logical.Execution queues schedule jobs for execution; generic and logicalqueues transfer jobs to execution queues. Within these majorclassifications, queue type is further defined by the kinds of job thequeues can accept for processing. Some types of execution and genericqueues accept batch jobs; other types accept print jobs. Logical queuesare restricted to print jobs.

You create a queue by making a call to $SNDJBC specifying theSJC$_CREATE_QUEUE function code. Item codes that you optionally specifyin the call determine the type of queue you create. The following listdescribes the various types of execution, generic, and logical queuesand indicates which item codes you need to specify to create them:

• Execution queue. An execution queue schedules jobs for processing. In an OpenVMS Cluster environment, jobs are processed on the node that manages the execution queue. There are two types of execution queues:
  • Batch execution queue. A batch execution queue can schedule only batch jobs for execution. A batch job executes as a detached process that sequentially runs one or more command procedures; you define the list of command procedures as part of the initial job description. You create a batch execution queue by specifying the SJC$_BATCH item code in the call to the $SNDJBC service.
  • Output execution queue. An output execution queue schedules print jobs for processing by an independent symbiont process associated with the queue. The job controller sends the symbiont a list of files to process; you define this list of files as part of the initial job description. As the symbiont processes each file, it produces output for the device, such as a printer or terminal, that it controls.
    The standard print symbiont image provided by the operating system is designed to print files on hardcopy devices. User-modified or user-written symbionts also can be designed for this or any other file processing activity managed by the batch and print queuing system. The symbiont image that executes jobs from an output queue is specified by the SJC$_PROCESSOR item code. If you omit this item code, the standard print symbiont image, PRTSMB, is associated with the queue.
    There are three types of output execution queue:
    1. Printer execution queue. This type of queue typically uses the standard print symbiont to direct output to a line printer. You can specify a user-provided symbiont in the SJC$_PROCESSOR item code. You create a printer execution queue by specifying the SJC$_PRINTER item code when you create the output execution queue. A printer execution queue is the default type of output execution queue.
    2. Terminal execution queue. This type of queue typically uses the standard print symbiont to direct output to a terminal printer. You can specify a user-provided symbiont in the SJC$_PROCESSOR item code. You create a terminal execution queue by specifying the SJC$_TERMINAL item code when you create the output execution queue.
    3. Server execution queue. This type of queue uses the user-modified or user-written symbiont you specify in the SJC$_PROCESSOR item code to process the files that belong to jobs in the queue. You create a server execution queue by specifying the SJC$_SERVER item code when you create the output execution queue.
    
    When you create an output execution queue, you can initially mark it as either a printer, terminal, or server execution queue. However, when the queue is started, the symbiont process associated with the queue can change the queue type from the type designated at its creation to a printer, terminal, or server execution queue, as follows:
    1. When an output execution queue associated with the standard print symbiont is started, the symbiont determines whether it is controlling a printer or terminal. It communicates this information to the job controller. If necessary, the job controller then changes the type designation of the output execution queue.
    2. When an output execution queue associated with a user-modified or user-written symbiont is started, the symbiont has the option of identifying the queue to the job controller as a server queue. If the user-written or user-modified symbiont does not notify the job controller that it wants to change the queue type designation, the output execution queue retains the queue type designation it received when it was created.
• Generic queue. A generic queue holds a job until an appropriate execution queue becomes available to initiate the job; the job controller then requeues the job to the available execution queue. In a cluster environment, a generic queue can direct jobs to execution queues that are located on other nodes in the cluster.
  You create a generic queue by specifying the SJC$_GENERIC_QUEUE item code in the call to the $SNDJBC service. You designate each execution queue to which the generic queue can direct jobs by specifying the SJC$_GENERIC_TARGET item code. Because a generic queue can direct jobs to more than one execution queue, you can specify the SJC$_GENERIC_TARGET item code up to 124 times in a single call to $SNDJBC to define a complete set of execution queues for any generic queue. If you do not specify the SJC$_GENERIC_TARGET item code, the generic queue directs jobs to any execution queue that is the same type of queue as the generic queue; that is, a generic batch queue will direct a job to any available batch execution queue, and so on. There is one exception: a generic queue will not direct work to any execution queue that was created in a call to $SNDJBC that specified the SJC$_NO_GENERIC_SELECTION item code.
  There are two types of generic queue:
  • Generic batch queue. A generic batch queue can direct jobs only to batch execution queues. You create a generic batch queue by specifying both the SJC$_GENERIC_QUEUE and SJC$_BATCH item codes in the call to the $SNDJBC service.
  • Generic output queue. A generic output queue can direct jobs to any of the three types of output execution queue: printer, terminal, or server. Creating a generic output queue that directs jobs to any combination of the three types of output execution queue is possible. Typically, however, when you create a generic output queue, you specify a list of type-specific target queues. This way, the generic output queue directs jobs to a single type of output execution queue. Thus, you can control whether the jobs submitted to the generic output execution queue are output on a line printer or a terminal printer or are sent to a server symbiont for processing. You create a generic output queue by specifying the SJC$_GENERIC_QUEUE item code in the call to the $SNDJBC service.
• Logical queue. A logical queue performs the same function as a generic output queue, except that a logical queue can direct jobs to only a single printer, terminal, or server execution queue. A logical queue is only an output queue that has been assigned to transfer its jobs to one execution queue.
  To change an output queue into a logical queue, you make a call to the $SNDJBC service while the output queue is in a stopped state. The call must specify the SJC$_ASSIGN_QUEUE function code and the SJC$_DESTINATION_QUEUE item code. You use the SJC$_DESTINATION_QUEUE item code to specify the execution queue to which the logical queue should direct jobs. When the logical queue is started, it automatically requeues its jobs to the specified execution queue as that execution queue becomes available. You can change a logical queue back to its original output queue definition by specifying the SJC$_DEASSIGN_QUEUE function code in a subsequent call to the $SNDJBC service.

Queue Protection

This section describes UIC-based protection checking that is performedby the $SNDJBC service to control access to queues.

As an alternative to this form of protection checking, you canassociate ACLs with queues using the appropriate security services. Seethe $GET_SECURITY and $SET_SECURITY system services for moreinformation.

There are two aspects to UIC-based queue protection:

• When you create a queue, you assign it a UIC by using the SJC$_OWNER_UIC item code. If you do not specify this item code, the queue is given the default UIC [1,4].
• You can assign a queue a protection mask by specifying the SJC$_PROTECTION item code. This protection mask specifies read, submit, manage, and delete access for the four categories of user: Owner, Group, World, and System.

In addition, certain queue operations require the caller of $SNDJBC tohave certain privileges. The function codes that require privileges arelisted in the Privileges and Restrictions section.

When a job is submitted to a queue, it is assigned a UIC that is thesame as the UIC of the process submitting the job, unless the SJC$_UICitem code is specified to supply a different UIC.

For each requested operation, the $SNDJBC service checks the UIC andprivileges of the requesting process against the UIC of the queue,protection specified for the queue, and the privileges, if any,required for the operation. This checking is performed in a way similarto the way that the file system checks access to a file by comparingthe owner UIC and protection of the file with the UIC and privileges ofthe requester.

Operations that apply to jobs are checked against read and deleteprotection specified for the queue in which the job is entered and theowner UIC of the job. In general, read access to a job allows you todetermine that the job exists; delete access to a job allows you toaffect the job.

Operations that apply to queues are checked against the submit andmanage protection specified for the queue and the owner UIC of thequeue. In general, submit access to a queue allows you to submit jobsto the queue; manage access to a queue allows you to act as an operatorfor the queue, including the ability to affect jobs in the queue, toaffect accounting, and to alter queues. OPER privilege grants manageaccess to all queues.

Privileges and Restrictions

To specify the following function codes, the caller must have both OPERand SYSNAM privilege:

SJC$_DELETE_QUEUE_MANAGER
SJC$_START_QUEUE_MANAGER
SJC$_STOP_QUEUE_MANAGER

To specify the following function codes, the caller must have OPERprivilege:

SJC$_CREATE_QUEUE
SJC$_DEFINE_CHARACTERISTIC
SJC$_DEFINE_FORM
SJC$_DELETE_CHARACTERISTIC
SJC$_DELETE_FORM
SJC$_DELETE_QUEUE
SJC$_START_ACCOUNTING
SJC$_STOP_ACCOUNTING

To specify the following function code, the caller can have OPERprivilege or manage access:

SJC$_DELETE_QUEUE

To specify the following function code, the caller must have OPERprivilege, execute access to the queue containing the specified job, orread access to the specified job:

SJC$_SYNCHRONIZE_JOB

To specify the following function codes, the caller must have OPERprivilege, manage access to the specified queue, or submit access tothe specified queue:

SJC$_ADD_FILE
SJC$_CLOSE_DELETE
SJC$_CLOSE_JOB
SJC$_CREATE_JOB
SJC$_ENTER_FILE

To specify the following function codes, the caller must have OPERprivilege or manage access to the specified queue or queues:

SJC$_ALTER_QUEUE
SJC$_ASSIGN_QUEUE
SJC$_DEASSIGN_QUEUE
SJC$_DISABLE_AUTOSTART
SJC$_ENABLE_AUTOSTART
SJC$_MERGE_QUEUE
SJC$_PAUSE_QUEUE
SJC$_RESET_QUEUE
SJC$_START_QUEUE
SJC$_STOP_ALL_QUEUES_ON_NODE
SJC$_STOP_QUEUE

To specify the following function codes, the caller must have OPERprivilege, manage access to the queue containing the specified job, ordelete access to the specified job:

SJC$_ABORT_JOB
SJC$_ALTER_JOB
SJC$_DELETE_JOB

To specify the following function codes, no privilege is required:

SJC$_BATCH_CHECKPOINT
SJC$_WRITE_ACCOUNTING

To specify a scheduling priority (using the SJC$_PRIORITY item code)higher than the value of the system parameter MAXQUEPRI, the callerneeds OPER or ALTPRI privilege.

To specify the following item codes, the caller must have OPERprivilege:

SJC$_OWNER_UIC
SJC$_PROTECTION

To specify the following item codes, the caller must have CMKRNLprivilege:

SJC$_ACCOUNT_NAME
SJC$_UIC
SJC$_USERNAME

Required Quota

To specify the astadr argument, the process must havesufficient ASTLM quota.

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,$SNDJBCW, $SNDOPR, $TRNLNM

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list or input buffer cannot be read by the caller; or the return length buffer, output buffer, or status block cannot be written by the caller.
SS$_BADPARAM	The function code is invalid; the item descriptor contains an invalid buffer length value; a buffer descriptor has an invalid length; or the reserved parameter has a nonzero value.
SS$_DEVOFFLINE	The job controller process is not running.
SS$_EXASTLM	You specified the astadr argument, and the process has exceeded its ASTLM quota.
SS$_ILLEFC	The efn argument specifies an illegal event flag number.
SS$_INSFMEM	Insufficient space exists for completing the request.
SS$_IVLOGNAM	Queue form or characteristic name is not a valid logical name.
SS$_MBFULL	The job controller mailbox is full.
SS$_MBTOOSML	The mailbox message is too large for the job controller mailbox.
SS$_SHELVED	The job controller attempted to access a shelved file. The service does not automatically unshelve files.
SS$_UNASEFC	The efn argument specifies an unassociated event flag cluster.

Condition Values Returned in the I/O Status Block

JBC$_NORMAL	The service completed successfully.
JBC$_AUTONOTSTART	The queue is autostart active, but not started. You have tried to start an autostart queue when none of its available nodes has autostart enabled.
JBC$_BUFTOOSMALL	The request could not be completely satisfied due to limited buffer size. The amount of information retrieved in response to the query exceeds the amount of data the queue manager can return in response to a single request.
JBC$_DELACCESS	The file protection of the specified file, which was entered with the delete option, does not allow delete access to the caller.
JBC$_DUPCHARNAME	The command specified a duplicate characteristic name. Each characteristic must have a unique name.
JBC$_DUPCHARNUM	The command specified a duplicate characteristic number. Each characteristic must have a unique number.
JBC$_DUPFORM	The specified form number is invalid because it is already defined; each form must have a unique form number.
JBC$_DUPFORMNAME	The command specified a duplicate form name. Each form must have a unique name.
JBC$_EMPTYJOB	The open job cannot be closed because it contains no files.
JBC$_EXECUTING	The parameters of the specified job cannot be modified because the job is currently executing.
JBC$_INCDSTQUE	The type of the specified destination queue is inconsistent with the requested operation.
JBC$_INCFORMPAR	The specified length, width, and margin parameters are inconsistent; the value of the difference between the top and bottom margin parameters must be less than the form length, and the difference between the left and right margin parameters must be less than the line width.
JBC$_INCOMPLETE	The requested queue management operation cannot be executed because a previously requested queue management operation has not yet completed.
JBC$_INCQUETYP	The type of the specified queue is inconsistent with the requested operation.
JBC$_INTERNALERROR	An internal error caused loss of process status. A system error prevented the queue manager from obtaining the completion status of a process.
JBC$_INVCHANAM	A specified characteristic name is not syntactically valid.
JBC$_INVDSTQUE	The destination queue name is not syntactically valid.
JBC$_INVFORNAM	The form name is not syntactically valid.
JBC$_INVFUNCOD	The specified function code is invalid.
JBC$_INVITMCOD	The item list contains an invalid item code.
JBC$_INVPARLEN	The length of a specified string is outside the valid range for that item code.
JBC$_INVPARVAL	A parameter value specified for an item code is outside the valid range for that item code.
JBC$_INVQUENAM	The queue name is not syntactically valid.
JBC$_ITMREMOVED	The meaningless items were removed from the request. One or more item codes not meaningful to this command were specified. The command is processed and the meaningless items are ignored.
JBC$_JOBNOTEXEC	The specified job is not executing.
JBC$_JOBQUEDIS	The request cannot be executed because the system job queue manager has not been started.
JBC$_JOBQUEENA	The system job queue manager cannot be started because it is already running.
JBC$_MISREQPAR	An item code that is required for the specified function code has not been specified.
JBC$_NOAUTOSTART	The node does not have the autostart feature enabled.
JBC$_NODSTQUE	The specified destination queue does not exist.
JBC$_NOOPENJOB	The requesting process did not open a job with the SJC$_CREATE_JOB function.
JBC$_NOPRIV	The queue protection denies access to the queue for the specified operation.
JBC$_NOQUESPACE	The system job queue file was full and could not be extended.
JBC$_NORESTART	The specified job cannot be requeued because it was not defined as restartable.
JBC$_NOSUCHCHAR	The specified characteristic does not exist.
JBC$_NOSUCHENT	There is no job with the specified entry number.
JBC$_NOSUCHFORM	The specified form does not exist.
JBC$_NOSUCHJOB	The specified job does not exist.
JBC$_NOSUCHMGR	The specified queue manager does not exist.
JBC$_NOSUCHNODE	The specified node does not exist.
JBC$_NOSUCHQUE	The specified queue does not exist.
JBC$_NOTALLREQUE	Not all jobs in the source queue could be requeued to the target queue. Some of the jobs specified were not suitable for execution on the specified target queue.
JBC$_NOTASSIGN	The specified queue cannot be deassigned because it is not assigned.
JBC$_NOTMEANINGFUL	The specified item code is no longer meaningful.
JBC$_NOTSUPPORTED	The specified item code or function code is not supported.
JBC$_PRIOSMALL	The scheduling priority has a smaller value than requested. A user without ALTPRI or OPER privilege specified a value for a job's priority that exceeded the queue's maximum priority for nonprivileged jobs. The job is entered in the queue, but its scheduling priority is lower than the value requested by the user.
JBC$_QMANNOTSTARTED	The queue manager could not be started.
JBC$_QUEDISABLED	The disabled queue cannot be modified, nor can jobs be submitted to it.
JBC$_QUENOTMOD	The modifications were not made because the queue was not stopped.
JBC$_QUENOTSTOP	The specified queue cannot be deleted because it is not in a stopped state.
JBC$_REFERENCED	The specified queue cannot be deleted because of existing references by other queues or jobs.
JBC$_STARTED	The specified queue cannot be started because it is already running.
JBC$_STKNOTCHANGE	The stock associated with a form cannot be changed.
JBC$_TOOMUCHINFO	The size of the data in request exceeds system constraints. The amount of data specified for a record within the queue manager's database is too large.

When you use the SJC$_SYNCHRONIZE_JOB function code, the return valueis the exit status of the specified job.

When you start a symbiont queue with the SJC$_START_QUEUE function codeor the SJC$_CREATE_QUEUE function code with the SJC$_CREATE_START itemcode, any error encountered by the symbiont process will be returned inthe IOSB.

Examples

$ vfyold = f$verify(1)$ create sys$scratch:accounting.c#include <efndef.h>#include <lib$routines.h>#include <sjcdef.h>#include <ssdef.h>#include <starlet.h>#include <stddef.h>#include <stsdef.h>struct ItemList3    {    short int ItemLength;    short int ItemCode;    void *ItemBuffer;    void *ItemRetLen;    };#define MAXITMLST 3main()  {  int i;  struct ItemList3 JbcIL[MAXITMLST];  unsigned short int IOSB[4];  int RetStat, JbcMask, JbcFunc;  /* To start accounting: */  JbcFunc = SJC$_START_ACCOUNTING;  /* Specify image and interactive */  JbcMask = SJC$M_ACCT_IMAGE | SJC$M_ACCT_INTERACTIVE;  i = 0;  JbcIL[i].ItemLength     = sizeof( JbcMask );  JbcIL[i].ItemCode       = SJC$_ACCOUNTING_TYPES;  JbcIL[i].ItemBuffer     = (void *) &JbcMask;  JbcIL[i++].ItemRetLen   = NULL;  JbcIL[i].ItemLength     = 0;  JbcIL[i].ItemCode       = 0;  JbcIL[i].ItemBuffer     = NULL;  JbcIL[i++].ItemRetLen   = NULL;  RetStat = sys$sndjbcw(EFN$C_ENF,JbcFunc,0, JbcIL,IOSB,0,0);  if (!$VMS_STATUS_SUCCESS( RetStat ))    lib$signal( RetStat );  if (!$VMS_STATUS_SUCCESS( IOSB[0] ))    lib$signal( IOSB[0] );  return SS$_NORMAL;  }$ cc/decc/prefix=all sys$scratch:accounting.c/object=sys$scratch:$ link/executable=sys$scratch:accounting.exe sys$scratch:accounting$ show accounting$ prvold = f$setprv("OPER")$ run sys$scratch:accounting$ show accounting$ priv = f$setprv(prvold)$ vfyold = f$verify(vfyold)$ exit      

This C program demonstrates an $SNDJBCW call.

! Declare system service related symbolsINTEGER*4       SYS$SNDJBCW,2               STATUSINCLUDE         '($SJCDEF)'! Define item list structureSTRUCTURE       /ITMLST/  UNION    MAP      INTEGER*2 BUFLEN, ITMCOD      INTEGER*4 BUFADR, RETADR    END MAP    MAP      INTEGER*4 END_LIST    END MAP  END UNIONEND STRUCTURE! Define I/O status block structureSTRUCTURE       /IOSBLK/INTEGER*4       STS, ZEROEDEND STRUCTURE! Declare $SNDJBCW item list and I/O status blockRECORD /ITMLST/ SUBMIT_LIST(6)RECORD /IOSBLK/ IOSB! Declare variables used in $SNDJBCW item listCHARACTER*9     QUEUE                   /'SYS$BATCH'/CHARACTER*23    FILE_SPECIFICATION      /'$DISK1:[COMMON]TEST.COM'/CHARACTER*12    USERNAME                /'PROJ3036    '/INTEGER*4       ENTRY_NUMBER! Initialize item list for the enter file operationSUBMIT_LIST(1).BUFLEN = 9SUBMIT_LIST(1).ITMCOD = SJC$_QUEUESUBMIT_LIST(1).BUFADR = %LOC(QUEUE)SUBMIT_LIST(1).RETADR = 0SUBMIT_LIST(2).BUFLEN = 23SUBMIT_LIST(2).ITMCOD = SJC$_FILE_SPECIFICATIONSUBMIT_LIST(2).BUFADR = %LOC(FILE_SPECIFICATION)SUBMIT_LIST(2).RETADR = 0SUBMIT_LIST(3).BUFLEN = 12SUBMIT_LIST(3).ITMCOD = SJC$_USERNAMESUBMIT_LIST(3).BUFADR = %LOC(USERNAME)SUBMIT_LIST(3).RETADR = 0SUBMIT_LIST(4).BUFLEN = 0SUBMIT_LIST(4).ITMCOD = SJC$_NO_LOG_SPECIFICATIONSUBMIT_LIST(4).BUFADR = 0SUBMIT_LIST(4).RETADR = 0SUBMIT_LIST(5).BUFLEN = 4SUBMIT_LIST(5).ITMCOD = SJC$_ENTRY_NUMBER_OUTPUTSUBMIT_LIST(5).BUFADR = %LOC(ENTRY_NUMBER)SUBMIT_LIST(5).RETADR = 0SUBMIT_LIST(6).END_LIST = 0! Call $SNDJBCW service to submit the batch jobSTATUS = SYS$SNDJBCW (,2               %VAL(SJC$_ENTER_FILE),,2               SUBMIT_LIST,2               IOSB,,)IF (STATUS) STATUS = IOSB.STSIF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))END      

This Fortran program demonstrates the use of the $SNDJBCW service tosubmit a batch job that is to execute on behalf of another user. No logfile is produced for the batch job. This program saves the job's entrynumber. You need CMKRNL privilege to run this program.

The Send to Job Controller and Wait and $GETQUI services togetherprovide the user interface to the Job Controller (JBC) facility. The$SNDJBCW service allows you to create, stop, and manage queues and thejobs in those queues. Queues can be generic, batch, execution, oroutput queues. Jobs can be batch or print jobs.

The $SNDJBCW service queues a request to the job controller. For mostoperations, $SNDJBCW completes synchronously; that is, it returns tothe caller after the operation completes; however, if the requestedoperation is a pause queue, stop queue, or abort job operation,$SNDJBCW returns to the caller after queuing the request. There is noway to synchronize completion of these operations. Also, $SNDJBCW doesnot wait for a job to complete before it returns to the caller. Tosynchronize completion of a job, the caller must specify theSJC$_SYNCHRONIZE_JOB function code.

The $SNDJBCW service is identical to the Send to Job Controller($SNDJBC) service except that $SNDJBC completes asynchronously; the$SNDJBC service returns to the caller immediately after queuing therequest, without waiting for the operation to complete.

For additional information about $SNDJBCW, refer to the documentationof $SNDJBC.

The $SNDJBC and $SNDJBCW services supersede the Send Message toSymbiont Manager ($SNDSMB) and Send Message to Accounting Manager($SNDACC) services. You should write new programs using $SNDJBC or$SNDJBCW, instead of $SNDSMB or $SNDACC. You should convert oldprograms using $SNDSMB or $SNDACC to use $SNDJBC or $SNDJBCW, asconvenient.

Format

SYS$SNDJBCW [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr] [,astprm]

C Prototype

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

Performs the following functions:

• Sends a user request to operator terminals
• Sends a user cancellation request to operator terminals
• Sends an operator reply to a user terminal
• Enables an operator terminal
• Displays the status of an operator terminal
• Initializes the operator log file

Format

SYS$SNDOPR msgbuf ,[chan]

C Prototype

int sys$sndopr (void *msgbuf, unsigned short int chan);

Arguments

msgbuf

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

User buffer specifying the operation to be performed and theinformation needed to perform that operation. Themsgbuf argument is the address of a character stringdescriptor pointing to the buffer.

The format and contents of the buffer vary with the requestedoperation; however, the first byte in any buffer is the request code,which specifies the operation to be performed. The $OPCMSG macrodefines the symbolic names for these request codes.

The following table shows each operation that $SNDOPR performs and therequest code that specifies that operation:

Request Code	Corresponding Operation
OPC$_RQ_CANCEL	Sends a user cancellation request to specified operator terminals. You use this request code to notify one or more operators that a previous request is to be canceled. To specify OPC$_RQ_CANCEL, you must also specify the chan argument.
OPC$_RQ_LOGI	Initializes the operator log file.
OPC$_RQ_REPLY	Sends an operator reply to a user who has made a request. Operators use this request code to report the status of a user request. The format of the message buffer for this request is the format of the reply found in the user's mailbox after the call to $SNDOPR completes. All functions of $SNDOPR that deliver a reply to a mailbox do so in the format described for this request code.
OPC$_RQ_RQST	Sends a user request to operator terminals. This request code is used to make an operator request. If you specify a reply to the request (by using the chan argument), the operator request is kept active until the operator responds.
OPC$_RQ_STATUS	Reports the status of an operator terminal. Operators use this request to display the operator classes for which the specified terminal is enabled and a list of outstanding requests.
OPC$_RQ_TERME	Enables an operator terminal. You use this request to enable a specified terminal to receive operator messages.

The following diagrams depict the message buffer for each of theserequest codes. Each field within a diagram has a symbolic name, whichserves to identify the field; in other words, these names specifyoffsets into the message buffer. The list following each diagram showseach field name and what its contents can or should be. The $OPCDEFmacro defines the field names, as well as any other symbolic name thatcan be specified as the contents of a field.

Message Buffer Format for OPC$_RQ_RQST

Message Buffer Format for OPC$_RQ_CANCEL

Message Buffer Format for OPC$_RQ_REPLY

Message Buffer Format for OPC$_RQ_TERME

Message Buffer Format for OPC$_RQ_STATUS

Message Buffer Format for OPC$_RQ_LOGI

chan

If a reply from the operator is desired, you must specify thechan argument.

Description

The $SNDOPR service performs the following functions:

• Sends a user request to operator terminals
• Sends a user cancellation request to operator terminals
• Sends an operator reply to a user terminal
• Enables an operator terminal
• Displays the status of an operator terminal
• Initializes the operator log file

This system service requires system dynamic memory; it cannot be calledfrom kernel mode.

The general procedure for using this service is as follows:

1. Construct the message buffer and place its final length in the first word of the buffer descriptor.
2. Call the $SNDOPR service.
3. Check the condition value returned in R0 to make sure the request was successfully made.
4. Issue a read request to the mailbox specified, if any.
5. When the read operation completes, check the 2-byte condition value in the OPC$W_MS_STATUS field to make sure that the operation was performed successfully.

The format of messages displayed on operator terminals follows:

%%%%%%%%%%% OPCOM dd-mmm-yyyy hh:mm:ss.ccmessage specific information

The following example shows the message displayed on a terminal as aresult of a request to enable that terminal as an operator terminal:

%%%%%%%%%%% OPCOM 30-DEC-2001 13:44:40.37Operator _NODE$LTA5: has been enabled, username HOEBLE

The following example shows the message displayed on an operatorterminal as a result of a request to display the status of thatoperator terminal:

%%%%%%%%%%% OPCOM 30-DEC-2001 12:11:10.48Operator status for operator _NODE$OPA0:CENTRAL, PRINTER, TAPES, DISKS, DEVICES, CARDS, CLUSTER, SECURITY,OPER1, OPER2, OPER3, OPER4, OPER5, OPER6, OPER7, OPER8, OPER9,OPER10, OPER11, OPER12

The following example shows the message displayed on an operatorterminal as a result of a user request:

%%%%%%%%%%% OPCOM 30-DEC-2001 12:57:32.25Request 1285, from user ROSS on NODE_NAMEPlease mount device _NODE$DMA0:

Required Access or Privileges

OPER privilege is required for the following functions:

• Enabling a terminal as an operator's terminal
• Replying to or canceling a user's request
• Initializing the operator communication log file

In addition, the operator must have SECURITY privilege to affectsecurity functions.

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

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The message buffer or buffer descriptor cannot be read by the caller.
SS$_BADPARAM	The specified message has a length of 0 or has more than 986 bytes.
SS$_DEVNOTMBX	The channel specified is not assigned to a mailbox.
SS$_INSFMEM	The service was called from kernel mode or the system dynamic memory is insufficient for completing the service.
SS$_IVCHAN	You specified an invalid channel number. An invalid channel number is one that is 0 or a number larger than the number of channels available.
SS$_MBFULL	The mailbox used to support communication is full. Retry at a later time.
OPC$_NOPERATOR	The service completed successfully; the Operator Communications Manager (OPCOM) is not running and the message will not be sent. Note that OPC$_NOPERATOR is a success status and must be tested for explicitly.
SS$_NOPRIV	The process does not have the privilege to reply to or cancel a user's request; the process does not have read/write access to the specified mailbox; or the channel was assigned from a more privileged access mode.

Condition Values Returned in the Mailbox

OPC$_BLANKTAPE	The service completed successfully; the operator responded with the DCL command REPLY/BLANK_TAPE=n.
OPC$_INITAPE	The service completed successfully; the operator responded with the DCL command REPLY/INITIALIZE_TAPE=n.
OPC$_NOPERATOR	The service completed successfully; no operator terminal was enabled to receive the message.
OPC$_RQSTCMPLTE	The service completed successfully; the operator completed the request.
OPC$_RQSTPEND	The service completed successfully; the operator will perform the request when possible.
OPC$_RQSTABORT	The operator could not satisfy the request.
OPC$_RQSTCAN	The caller canceled the request.

Examples

#include <ssdef.h>#include <opcdef.h>#include <string.h>#include <descrip.h>#include <starlet.h>#include <lib$routines.h>char    input_buffer[256];      /* Input buffer, if needed *//* VMS descriptors: */$DESCRIPTOR(input_desc, input_buffer);$DESCRIPTOR(prompt_desc, "Request> ");struct dsc$descriptor req_desc;main(int argc, char *argv[]){    int status,                 /* Status of system calls */        length = 0;             /* Length of message text */    struct OPC request;         /* Request message buffer */    /* Check for too many arguments on command line */    if (argc > 2)        return (SS$_OVRMAXARG);    /* See if request string present on command line... */    if (argc > 1)    {        /* It is.  Compute length and copy pointer */        length = strlen(argv[1]);        input_desc.dsc$a_pointer = argv[1];    }    /* If no message present, prompt user for message text */    while (length == 0)    {        status = lib$get_input(&input_desc, &prompt_desc, &length);        if (status != SS$_NORMAL)            return (status);    };    if (length > 128)           /* Limit message length */        length = 128;           /*    to 128 characters */    /* Set up request buffer... */    request.opc$b_ms_type = OPC$_RQ_RQST;    request.opc$b_ms_target = OPC$M_NM_CENTRL;    request.opc$l_ms_rqstid = 0;    memcpy(&request.opc$l_ms_text, input_desc.dsc$a_pointer, length);    /* Set up request buffer descriptor and send message */    req_desc.dsc$w_length = length + 8;    req_desc.dsc$a_pointer = (char *) &request;    return (sys$sndopr(&req_desc, 0));}      

This example allows you to build an operator request and send therequest to the operator.

IMPLICIT NONE        ! Symbol definitions        INCLUDE '($DVIDEF)'        INCLUDE '($OPCDEF)'        ! Structures for SNDOPR        STRUCTURE /MESSAGE/         UNION          MAP           BYTE TYPE,        2       ENABLE(3)           INTEGER*4 MASK           INTEGER*2 OUNIT           CHARACTER*14 ONAME          END MAP          MAP           CHARACTER*24 STRING          END MAP         END UNION        END STRUCTURE        RECORD /MESSAGE/ MSGBUF        ! Length of MSGBUF.ONAME        INTEGER*4 ONAME_LEN        ! Status and routines        INTEGER*4 STATUS,        2         LIB$GETDVI,        2         SYS$SNDOPR        ! Type        MSGBUF.TYPE = OPC$_RQ_TERME        ! Enable        MSGBUF.ENABLE(1) = 1        ! Operator type        MSGBUF.MASK = OPC$M_NM_OPER1        ! Terminal unit number        STATUS = LIB$GETDVI (DVI$_UNIT,        2                    ,        2                    'SYS$OUTPUT',        2                    MSGBUF.OUNIT,,)        IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))        ! Terminal name        STATUS = LIB$GETDVI (DVI$_FULLDEVNAM,        2                    ,        2                    'SYS$OUTPUT',,        2                    MSGBUF.ONAME,        2                    ONAME_LEN)        IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))        ! Remove unit number from ONAME and set up counted string        ONAME_LEN = ONAME_LEN - 3        MSGBUF.ONAME(2:ONAME_LEN+1) = MSGBUF.ONAME(1:ONAME_LEN)        MSGBUF.ONAME(1:1) = CHAR(ONAME_LEN)        ! Call $SNDOPR        STATUS = SYS$SNDOPR (MSGBUF.STRING,)        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))        END      

This HP Fortran for OpenVMS program enables the current terminal toreceive OPER1 operator messages.

The Space service lets you space (skip) a tape file forward or backwarda specified number of blocks.

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

On Alpha systems, initializes user image alignment fault reporting.

Format

SYS$START_ALIGN_FAULT_REPORT report_method ,report_buffer ,buffer_length

C Prototype

int sys$start_align_fault_report (int report_method, void*report_buffer, int buffer_length);

Arguments

report_method

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read
mechanism:	by value

Method by which image alignment faults are to be reported.

The following table shows valid values for thereport_method argument:

Value	Meaning
AFR$C_BUFFERED	Alignment fault PCs and fault addresses are saved in a user-supplied buffer.
AFR$C_EXCEPTION	Alignment faults are elevated to user mode exceptions.

report_buffer

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

The 32-bit address of the buffer into which to write the fault data.The report_buffer argument is needed only if the valueof the report_method argument is AFR$C_BUFFERED.

buffer_length

OpenVMS usage:	byte count
type:	longword (signed)
access:	read
mechanism:	by value

Length of the buffer specified in the report_bufferargument.

The buffer must have a minimum size of AFR$K_USER_LENGTH + 32. However,a larger buffer allows for more information to be collected.

Description

The Start Alignment Fault Reporting service initializes user imagealignment fault reporting.

The $START_ALIGN_FAULT_REPORT service allows the user to gatheralignment fault data for one image. Reporting is enabled for the lifeof the image. When the image terminates, the alignment fault reportingis disabled.

User alignment fault data can be written to a buffer or broadcast as aninformational exception message.

If the AFR$C_BUFFERED value is given in thereport_method buffer, alignment fault PCs and faultaddresses are saved in a user-supplied buffer.

The following diagram illustrates the format in which user alignmentfault data is stored in the buffer:

If the AFR$C_EXCEPTION value is given in thereport_method argument, alignment faults are elevatedto user mode exceptions. These exceptions can be trapped in a handler;otherwise, an informational exception message might be broadcast andthe program continues to execute.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,$PERM_REPORT_ALIGN_FAULT, $STOP_ALIGN_FAULT_REPORT,$STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The buffer specified in the report_buffer argument is not accessible.
SS$_AFR_ENABLED	The service has already been called for this image.
SS$_ARG_GTR_32_BITS	The report buffer's virtual address lies in 64-bit virtual address space.
SS$_ALIGN	The buffer specified in the report_buffer argument is not quadword aligned.
SS$_BADPARAM	The buffer size is smaller than that defined by the AFR$K_USER_LENGTH + 32 symbol.

Example

#include <afrdef>#include <stdio>#include <ssdef>#define USER_BUFFER_ITEMS  10#define GET_BUFFER_SIZE    USER_BUFFER_ITEMS*AFR$K_USER_LENGTH#define SAVE_BUFFER_SIZE   128+64#define fault_pc afr$l_fault_pc_l#define fault_va afr$l_fault_va_lstatic int usr_buff_len;static char *usr_buff;static int rep_method;voidcause_af(){  int     addr;  int     *ptr;  int    arr[2];  addr = (int) &arr[0];  ptr = (int *) ++addr;  *ptr = 1;    /* cause alignment fault */}main(){  int            i;  char           get_buffer[GET_BUFFER_SIZE];  struct afrdef  *data_item;  int            offset;  int            status;  int            return_size;  rep_method = AFR$C_BUFFERED;  usr_buff_len = SAVE_BUFFER_SIZE;  usr_buff = (char *)malloc (usr_buff_len);  if(( status = sys$start_align_fault_report(rep_method, usr_buff,               usr_buff_len))      != SS$_NORMAL) return(status);  for (i=0;i<USER_BUFFER_ITEMS;i++)    cause_af();  while (((status = sys$get_align_fault_data (get_buffer,                GET_BUFFER_SIZE,                &return_size)) > 0) &&         (return_size > 0)) {    /* got some data, print it */    offset = 0;    while (offset < return_size) {      data_item = (struct afrdef *)(&get_buffer[offset]);      printf ("Alignment fault at PC = %8.8X, VA = %8.8X\n",        data_item->fault_pc, data_item->fault_va);      offset += AFR$K_USER_LENGTH;    }  }  return (status);}      

This example shows how to use the $START_ALIGN_FAULT_REPORT service toinitialize user image alignment fault reporting on Alpha systems.

Adds a new branch to a transaction.

Format

SYS$START_BRANCH [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid ,tm_name,bid [,[timout], [acmode], [tx_class]]

C Prototype

int sys$start_branch (unsigned int efn, unsigned int flags, struct_iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned inttid [4], void *tm_name, unsigned int bid [4],...);

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, described in Table SYS-56. All undefined bits must be 0. Ifthis argument is omitted, no flags are used.

Table SYS-56 $START_BRANCH Option Flags

Flag Name	Description
DDTM$M_BRANCH_UNSYNCHED	Specifies that the new branch is unsynchronized. If this flag is clear, the new branch is synchronized.
DDTM$M_NONDEFAULT	Set this flag if you do not want the transaction to be the default transaction of the calling process. If this flag is clear, the transaction becomes the default transaction of the calling process. An error is returned if this flag is clear and the calling process has an current default transaction.
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.

iosb

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

The I/O status block in which the completion status of the service isreturned as a condition value. See the Condition Values Returnedsection.

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

astadr

astprm

tid

tm_name

To ensure smooth operation in a mixed-network environment, refer to thechapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, forinformation on defining node names.

bid

An BID value of zero is invalid.

timout

acmode

This argument only influences the access mode of the first branch inthis process. Subsequent branches have the same access mode as thefirst. The access mode of the new branch is the least privileged of:

• The access mode of the caller.
• The access mode specified by the acmode argument.

Note that if a branch already exists in this process, then neither theaccess mode of the caller nor the access mode specified by theacmode argument may be less privileged than thatbranch.

The default value of this argument is the access mode of the caller.

tx_class

This argument is ignored if the transaction already has a transactionclass on the local node.

This string must be no longer than 31 characters.

Description

The $START_BRANCH system service:

• Adds a new branch running in the calling process to the specified transaction.
• Adds the local DECdtm transaction manager to the specified transaction if the local DECdtm transaction manager is not already a participant in that transaction.
• Sets the default transaction of the calling process to the new transaction, if the DDTM$M_NONDEFAULT flag is clear and the process does not have a default transaction.
• Delivers a transaction started event to each RMI in the calling process that meets both of the following conditions:
  • Requested Transaction Started events for the corresponding transaction type (default or non-default)
  • Has an access mode that is the same as or more privileged than that specified in this call to $START_BRANCH.

The new branch should have been previously authorized. Authorization isprovided either by a matching call to $JOIN_RM with theDDTM$M_COORDINATOR flag set or by a matching call to $ADD_BRANCH. Twocalls, one to $ADD_BRANCH and one to $START_BRANCH or one to $JOIN_RMand one to $START_BRANCH, are said to be matching when the followingconditions are true:

• The same TID values are passed to both calls.
• The BID returned by the call to $ADD_BRANCH or $JOIN_RM is the same as that passed to the call to $START_BRANCH.
• The call to $START_BRANCH is made on the node identified by the tm_name argument passed to the call to $ADD_BRANCH or on the node on which the call to $JOIN_RM was made.
• The call to $ADD_BRANCH or $JOIN_RM is made on the node identified by the tm_name argument passed to the call to $START_BRANCH.

$START_BRANCH does not check that there has been a matching call to$ADD_BRANCH or $JOIN_RM unless the tm_name argumentpassed to $START_BRANCH specifies the local node.

Note The atomicity of the transaction is not guaranteed if there is a callto $START_BRANCH that does not have a matching call to $ADD_BRANCH or$JOIN_RM.

Preconditions for the successful completion of $START_BRANCH are:

• The local node must have a DECdtm transaction log.
• The TP_SERVER process must be running on the local node.
• There must not have been a successful call to $START_BRANCH on the local node that passed the specified BID.
• If the tm_name argument specifies the local node, there must have been a matching call to $ADD_BRANCH or $JOIN_RM on the local node.
• If the DDTM$M_NONDEFAULT flag is clear, the calling process must not have an unended default transaction.
• If this process already contains a branch of this transaction, then the access mode of the caller must be the same as or more privileged than the access mode of that branch.

$START_BRANCH may fail because:

• Preconditions were not met.
• An abort event occurred for the transaction.
• A call to $END_TRANS to end the transaction is in progress and it is too late to add a new branch to the transaction.
• The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process is in progress.

When $START_BRANCH completes successfully:

• A new branch running in the calling process has been added to the transaction.
• All Transaction Started events reported to RMIs in the calling process have been acknowledged.
• If the DDTM$M_NONDEFAULT flag was clear, the transaction is the default transaction of the calling process.

A branch may:

• Invoke resource manager operations, explicitly passing the TID.
• Invoke resource manager operations without specifying the TID, if the transaction is the default transaction of the calling process, and the resource manager supports default transactions.
• Call $ADD_BRANCH to authorize another branch to be added to the transaction.

(The way to invoke a resource manager operation is defined by theinterfaces provided by the resource manager; refer to the resourcemanager documentation.)

A synchronized branch is removed from the transaction by calling$END_BRANCH, specifying the appropriate BID and TID. An unsynchronizedbranch is removed from the transaction by DECdtm during commit or abortprocessing.

The branch is also removed from the transaction (and the transactionaborted):

• On termination of the current image or process.
• On successful completion of a call to $ABORT_TRANS in the calling process that passes the appropriate TID and BID.

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

Required Privileges

None

Required Quotas

BYTLM, ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $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_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$_ACCVIO	An argument was not accessible to the caller.
SS$_ALRCURTID	Either: An attempt was made to make the transaction specified by the tid argument the default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process had an unended default transaction. The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process was in progress.
SS$_BADPARAM	Either the options flags were invalid or the tid argument was omitted but the bid argument was not zero.
SS$_BRANCHSTARTED	There has already been a call to $START_BRANCH on the local node specifying that TID and BID (returned only if the node specified by the tm_name argument was the local node).
SS$_CONNECFAIL	The node specified by the tm_name argument was not the local node, and there was no communications link between the DECdtm transaction managers on the local node and the specified node.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_EXQUOTA	The job buffered I/O byte limit quota (BYTLM) 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$_INVBUFLEN	The string passed in the tx_class argument was longer than 31 characters, or the string passed in the tm_name argument was longer than 256 characters.
SS$_NOLOG	The local node did not have a transaction log.
SS$_NOSUCHBID	Either: The specified BID was not returned by any call to $ADD_BRANCH or $JOIN_RM on the local node (returned only if the node specified by the tm_name argument was the local node). An BID of zero was supplied.
SS$_NOSUCHTID	The local node did not have any branches in the specified transaction (returned only if the node specified by the tm_name argument was the local node).
SS$_TPDISABLED	The TP_SERVER process was not running on the local node.
SS$_WRONGSTATE	The transaction was in the wrong state for the attempted operation because either: An abort event has occurred for the transaction. A call to $END_TRANS to end the transaction is in progress and it is now too late to add a new branch to the transaction.

Adds a new branch to a transaction.

$START_BRANCHW always waits for the request to complete beforereturning to the caller. Other than this, it is identical to$START_BRANCH.

Format

SYS$START_BRANCHW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid,tm_name ,bid [,[timout] ,[acmode], [tx_class]]

C Prototype

int sys$start_branchw (unsigned int efn, unsigned int flags, struct_iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned inttid [4], void *tm_name, unsigned int bid [4],...);

Starts a new transaction.

Format

SYS$START_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid],[timout] ,[acmode] ,[tx_class]]

C Prototype

int sys$start_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 described in Table SYS-57. All undefined bits must be0. If this argument is omitted, no flags are used.

Table SYS-57 $START_TRANS Option Flags

Flag	Description
DDTM$M_NONDEFAULT	Set this flag if you do not want the new transaction to be the default transaction of the calling process. An error is returned if this flag is set and the tid argument is zero or omitted. If this flag is clear, the new transaction becomes the default transaction of the calling process. An error is returned if this flag is clear and the calling process already has a default transaction.
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 AST routine is not called, the event flag is not set, and the I/O status block is not filled in.

iosb

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

I/O status block in which the completion status of the service isreturned as a condition value. See the Condition Values Returnedsection.

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

astadr

astprm

tid

No other call to $START_TRANS on any node ever returns the same TIDvalue.

The default value of this argument is zero. An error is returned if theDDTM$M_NONDEFAULT flag is set and this argument is either omitted orzero.

timout

A positive time value specifies an absolute time. The absolute value ofa negative time specifies an offset (delta time) from the current time.

The transaction is aborted at the next timer interval if you specify either a zero time value or any time in the past. If this argument is omitted, the new transaction has no timeout.

acmode

An access mode is maintained for each transaction per process. Allbranches in a transaction in a process have the same access mode.Subsequent operations do not alter it. The access mode of a branch isthe least privileged mode in which a successful call to $END_TRANS maybe made.

Note that the transaction may be aborted by a call to $ABORT_TRANS fromany access mode.

The access mode of the branch is the least privileged of the following:

• The access mode of the caller
• The access mode specified by the acmode argument

If the acmode argument is omitted, the access mode ofthe new branch is the same as that of the caller.

tx_class

This string must be no longer than 31 characters. If this argument isomitted or the string is of length zero, the new transaction has notransaction class on the local node. In this case, the class of thetransaction on the local node can be specified by a subsequent call to$START_BRANCH on that node.

Description

The $START_TRANS system service starts a new transaction whose commitor abort processing is to be coordinated by the local DECdtmtransaction manager. The service:

• Adds a branch running in the calling process to the new transaction. The identifier (BID) of the new branch is 0.
• Sets the default transaction of the calling process to the new transaction, if the DDTM$M_NONDEFAULT flag is clear and the process does not have a default transaction.
• Delivers an event of type Transaction Started to each RMI in the calling process that requested Transaction Started events and has an access mode that is the same as or more privileged than that specified in this call to $START_TRANS. See the description of the acmode argument.

The event delivered to all such RMIs is either a defaulttransaction-started event or a nondefault transaction-started event,depending on whether the DDTM$M_NONDEFAULT flag is clear or not.

Preconditions for the successful completion of $START_TRANS are:

• The local node must have a DECdtm transaction log.
• The TP_SERVER process must be running on the local node.
• If the DDTM$M_NONDEFAULT flag is clear, the calling process must not have an unended default transaction.

$START_TRANS may fail for various reasons including:

• Preconditions were not met.
• The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process is in progress.

When $START_TRANS completes successfully:

• A new transaction has started, with a unique identifier.
• The transaction has a single branch, with a BID of 0.
• All Transaction Started events reported to RMIs in the calling process have been acknowledged.
• If the DDTM$M_NONDEFAULT flag was clear, the transaction is the default transaction of the calling process.

A branch may:

• Invoke resource manager operations, explicity passing the TID.
• Invoke resource manager operations without specifying the TID, if the transaction is the default transaction of the calling process, and the resource manager supports default transactions.
• Call $ADD_BRANCH to authorize another branch to be added to the transaction.

(The way to invoke a resource manager operation is defined by theinterfaces provided by the resource manager. Refer to the resourcemanager documentation for additional information.)

DECdtm cannot commit the transaction until the process calls $END_TRANS.

The transaction is aborted:

• On termination of the current image or process.
• On successful completion of a call to $ABORT_TRANS in the calling process, specifying a BID of 0.

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

Required Access or Privileges

None

Required Quotas

ASTLM, BYTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $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_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$_ACCVIO	An argument was not accessible to the caller.
SS$_ALCURTID	Either: An attempt was made to start a default transaction (the DDTM$M_NONDEFAULT flag was clear) when the calling process had an unended default transaction. The DDTM$M_NONDEFAULT flag was clear and a call to $SET_DEFAULT_TRANS by the calling process was in progress.
SS$_BADPARAM	Either the DDTM$M_NONDEFAULT flag was set and the tid argument was omitted, or the options flags were invalid.
SS$_CURTIDCHANGE	The DDTM$M_NONDEFAULT flag was clear 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$_EXQUOTA	The job buffered I/O byte limit quota (BYTLM) 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$_INVBUFLEN	The string passed to the tx_class argument was longer than 31 characters.
SS$_NOLOG	The local node did not have a transaction log.
SS$_TPDISABLED	The TP_SERVER process was not running on the local node.

Starts a new transaction.

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

Format

SYS$START_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm] ,[tid],[timout] ,[acmode]]

C Prototype

int sys$start_transw (unsigned int efn, unsigned int flags, struct_iosb *iosb,...);

On Alpha systems, disables user image alignment fault reporting.

Format

SYS$STOP_ALIGN_FAULT_REPORT

C Prototype

int sys$stop_align_fault_report (void);

Arguments

None.

Description

The Stop Alignment Fault Reporting service disables user imagealignment fault reporting.

The service returns SS$_AFR_NOT_ENABLED if user image alignment faultreporting is not enabled; otherwise, it returns success.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,$PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT,$STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_AFR_NOT_ENABLED	The $START_ALIGN_FAULT_REPORT service has not been called.

On Alpha systems, disables systemwide alignment fault reporting.

Format

SYS$STOP_SYS_ALIGN_FAULT_REPORT

C Prototype

int sys$stop_sys_align_fault_report (void);

Arguments

None.

Description

The Stop System Alignment Fault Reporting service disables systemwidealignment fault reporting.

The service returns SS$_AFR_NOT_ENABLED if systemwide alignment faultreporting is not enabled; otherwise, it returns success.

Required Access or Privileges

CMKRNL privilege is required.

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,$PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_NOPRIV	The caller lacks sufficient privilege.
SS$_AFR_NOT_ENABLED	The $START_ALIGN_FAULT_REPORT service has not been called.

Saves or restores the process image rights for the current protectedsubsystem.

Format

SYS$SUBSYSTEM enbflg

C Prototype

int sys$subsystem (unsigned int enbflg);

Argument

enbflg

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

Value specifying whether the protected subsystem identifiers are to besaved or restored. If the enbflg argument is set to 0,the active subsystem is saved. If it is set to 1, the subsystem isrestored.

Description

A protected subsystem image is a main image that has in its accesscontrol list a special type of ACE that names a set of identifiers andtheir attributes. Whenever the operating system activates a main imagethat has protected subsystem identifiers associated with it, theseidentifiers are automatically granted to the process for the durationof the image.

In essence, a protected subsystem provides the same behavior as if theimage had been installed with the identifiers. Subsystem identifiersare sometimes referred to as image rights, in contrast to processrights and system rights.

The Subsystem service provides an easy way for a protected subsystemimage to dynamically save and restore its subsystem identifiers. Aprotected subsystem might choose to turn off its subsystem identifiersat certain times to temporarily revoke the user's access to the objectscomprising the protected subsystem. For example, DCL uses the$SUBSYSTEM service to temporarily remove any image identifiers from theprocess during Ctrl/Y interrupt processing.

The image rights are saved in the process control region andautomatically deleted on image rundown ($RMSRUNDWN).

For more information about protected subsystems, refer to theHP OpenVMS Guide to System Security.

Required Access or Privileges

None

Required Quota

None

Related Services

None

Condition Values Returned

SS$_WASCLR	The service completed successfully; protected subsystem had no identifiers associated with it.
SS$_WASSET	The service completed successfully; protected subsystem had identifiers associated with it.

Allows a process to suspend itself or another process.

Format

SYS$SUSPND [pidadr] ,[prcnam] ,[flags]

C Prototype

int sys$suspnd (unsigned int *pidadr, void *prcnam, unsigned int flags);

Arguments

pidadr

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

Process identification (PID) of the process to be suspended. Thepidadr argument is the address of the longword PID.

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

You must specify the pidadr argument to suspend aprocess whose UIC group number is different from that of the callingprocess.

prcnam

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

Name of the process to be suspended. The prcnamargument is the address of a character string descriptor pointing tothe process name. A process running on the local node can be identifiedwith a 1- to 15-character string.

To identify a process on a particular node on a cluster, specify thefull process name, which includes the node name as well as the processname. The full process name can contain up to 23 characters.

A process name is implicitly qualified by its UIC group number. Becauseof this, you can use the prcnam argument only tosuspend processes in the same UIC group as the calling process.

To suspend processes in other groups, you must specify thepidadr argument.

flags

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

Longword of bit flags specifying options for the suspend operation.Currently, only bit 0 is used for the flags argument.When bit 0 is set, the process is suspended at kernel mode and ASTs arenot deliverable to the process.

To request a kernel mode suspend, the caller must be in either kernelmode or executive mode. The default (bit 0 is clear) is to suspend theprocess at supervisor mode, where executive or kernel mode ASTs can bedelivered to the process. If executive or kernel mode ASTs have beendelivered to a process suspended at supervisor mode, that process willreturn to its suspended state after the AST routine executes.

Description

The Suspend Process service allows a process to suspend itself oranother process.

A suspended process can receive executive or kernel mode ASTs, unlessit is suspended at kernel mode. If a process is suspended at kernelmode, the process cannot receive any ASTs or otherwise be executeduntil another process resumes or deletes it. If you specify neither thepidadr nor the prcnam argument, thecaller process is suspended.

If the longword value at address pidadr is 0, the PIDof the target process is returned.

The $SUSPND service requires system dynamic memory.

The $SUSPND service completes successfully if the target process isalready suspended.

Unless it has pages locked in the balance set, a suspended process canbe removed from the balance set to allow other processes to execute.

Note that a kernel mode suspend request can override a supervisor modesuspend state, but a supervisor suspend request cannot override akernel mode suspend state.

The Resume Process ($RESUME) service allows a suspended process tocontinue. If one or more resume requests are issued for a process thatis not suspended, a subsequent suspend request completes immediately;that is, the process is not suspended. No count is maintained ofoutstanding resume requests.

Note When the $SUSPND service is called and the target process is on adifferent cluster node than that of the process calling the $SUSPNDservice, the kernel mode suspend flag (bit 0) is ignored. As a result,any suspend is treated as a supervisor-mode suspend.

Required Access or Privileges

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

• GROUP privilege to suspend another process in the same group, unless the process to be suspended has the same UIC as the calling process
• WORLD privilege to suspend any other process in the system

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,$HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM,$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 completing the service.
SS$_IVLOGNAM	The specified process name has a length of 0 or has more than 15 characters.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.
SS$_NOPRIV	The target process was not created by the caller and the calling process does not have GROUP or WORLD privilege, or flag bit 0 was set from outer mode.
SS$_NOSUCHNODE	The process name refers to a node that is not currently recognized as part of the OpenVMS Cluster system.
SS$_NOSUSPEND	The process was previously marked as not suspendable by the PCB$V_NOSUSPEND flag.
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.)
SS$_WAIT_CALLERS_MODE	Bit 1 was used in the flags argument.

Checks the completion status of a system service that completesasynchronously.

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

Format

SYS$SYNCH [efn] ,[iosb]

C Prototype

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

Arguments

efn

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

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

iosb

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

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

Description

The Synchronize service checks the completion status of a systemservice that completes asynchronously. The service whose completionstatus is to be checked must have been called with theefn and iosb arguments specified,because the $SYNCH service uses the event flag and I/O status block ofthe service to be checked.

This service performs a true test for the completion of an asynchronousservice, such as $GETJPI. $SYNCH operates in the following way:

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

The $SYNCH service always sets the specified event flag when it returnsto the caller. This ensures that different program segments can use thesame event flag without conflicting. For example, assume that calls to$GETJPI and $GETSYI both specify the same event flag and that $SYNCH iscalled to check for the completion of $GETJPI. If $GETSYI sets theevent flag, $SYNCH clears the flag and waits for $GETJPI to set it.When $GETJPI sets the flag, $SYNCH returns to the caller and sets theevent flag. In this way, the flag set by $GETSYI is not lost, andanother call to $SYNCH will show the completion of $GETSYI.

The $SYNCH service is useful when a program calls an asynchronousservice but must perform some other work before testing for thecompletion of the asynchronous service. In this case, the programshould call $SYNCH at that point when it must know that the service hascompleted and when it is willing to wait for the service to actuallycomplete.

When a program calls an asynchronous service (for example, $QIO) andactually waits in line (by calling $WAITFR) for its completion withoutperforming any other work, you could improve that program by callingthe synchronous form of that service (for example, $QIOW). Thesynchronous services such as $QIOW execute code that checks for thetrue completion status in the same way that $SYNCH does.

Required Access or Privileges

None

Required Quota

None

Condition Values Returned

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