HP OpenVMS System Services Reference Manual


Previous Contents Index

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

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


Examples

#1

$ 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 3 
main() 
  { 
  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.

#2

! Declare system service related symbols 
INTEGER*4       SYS$SNDJBCW, 
2               STATUS 
INCLUDE         '($SJCDEF)' 
 
! Define item list structure 
STRUCTURE       /ITMLST/ 
  UNION 
    MAP 
      INTEGER*2 BUFLEN, ITMCOD 
      INTEGER*4 BUFADR, RETADR 
    END MAP 
    MAP 
      INTEGER*4 END_LIST 
    END MAP 
  END UNION 
END STRUCTURE 
 
! Define I/O status block structure 
STRUCTURE       /IOSBLK/ 
INTEGER*4       STS, ZEROED 
END STRUCTURE 
 
! Declare $SNDJBCW item list and I/O status block 
RECORD /ITMLST/ SUBMIT_LIST(6) 
RECORD /IOSBLK/ IOSB 
! Declare variables used in $SNDJBCW item list 
CHARACTER*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 operation 
SUBMIT_LIST(1).BUFLEN = 9 
SUBMIT_LIST(1).ITMCOD = SJC$_QUEUE 
SUBMIT_LIST(1).BUFADR = %LOC(QUEUE) 
SUBMIT_LIST(1).RETADR = 0 
SUBMIT_LIST(2).BUFLEN = 23 
SUBMIT_LIST(2).ITMCOD = SJC$_FILE_SPECIFICATION 
SUBMIT_LIST(2).BUFADR = %LOC(FILE_SPECIFICATION) 
SUBMIT_LIST(2).RETADR = 0 
SUBMIT_LIST(3).BUFLEN = 12 
SUBMIT_LIST(3).ITMCOD = SJC$_USERNAME 
SUBMIT_LIST(3).BUFADR = %LOC(USERNAME) 
SUBMIT_LIST(3).RETADR = 0 
SUBMIT_LIST(4).BUFLEN = 0 
SUBMIT_LIST(4).ITMCOD = SJC$_NO_LOG_SPECIFICATION 
SUBMIT_LIST(4).BUFADR = 0 
SUBMIT_LIST(4).RETADR = 0 
SUBMIT_LIST(5).BUFLEN = 4 
SUBMIT_LIST(5).ITMCOD = SJC$_ENTRY_NUMBER_OUTPUT 
SUBMIT_LIST(5).BUFADR = %LOC(ENTRY_NUMBER) 
SUBMIT_LIST(5).RETADR = 0 
SUBMIT_LIST(6).END_LIST = 0 
 
! Call $SNDJBCW service to submit the batch job 
STATUS = SYS$SNDJBCW (, 
2               %VAL(SJC$_ENTER_FILE),, 
2               SUBMIT_LIST, 
2               IOSB,,) 
IF (STATUS) STATUS = IOSB.STS 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
END 
 
      

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


$SNDJBCW

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

The $SNDJBCW service queues a request to the job controller. For most operations, $SNDJBCW completes synchronously; that is, it returns to the caller after the operation completes; however, if the requested operation is a pause queue, stop queue, or abort job operation, $SNDJBCW returns to the caller after queuing the request. There is no way to synchronize completion of these operations. Also, $SNDJBCW does not wait for a job to complete before it returns to the caller. To synchronize completion of a job, the caller must specify the SJC$_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 the request, without waiting for the operation to complete.

For additional information about $SNDJBCW, see the documentation of $SNDJBC.

The $SNDJBC and $SNDJBCW services supersede the Send Message to Symbiont 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 old programs using $SNDSMB or $SNDACC to use $SNDJBC or $SNDJBCW, as convenient.


Format

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


C Prototype

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


$SNDOPR

Performs the following functions:

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 the information needed to perform that operation. The msgbuf argument is the address of a character string descriptor pointing to the buffer.

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

The following table shows each operation that $SNDOPR performs and the request 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 these request codes. Each field within a diagram has a symbolic name, which serves to identify the field; in other words, these names specify offsets into the message buffer. The list following each diagram shows each field name and what its contents can or should be. The $OPCDEF macro defines the field names, as well as any other symbolic name that can be specified as the contents of a field.

Message Buffer Format for OPC$_RQ_RQST


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_RQST.
OPC$Z_MS_TARGET_CLASSES This 3-byte field contains a 24-bit bit vector that specifies which operator terminal types are to receive the request. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$L_MS_RQSTID This longword field contains a user-supplied longword message code.
OPC$L_MS_TEXT This variable-length field contains an ASCII string specifying text to be sent to the specified operator terminals. $SNDOPR uses the buffer size of the device to which the message is being sent.

Message Buffer Format for OPC$_RQ_CANCEL


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_CANCEL.
OPC$Z_MS_TARGET_CLASSES This 3-byte field contains a 24-bit bit vector that specifies which operator terminal types are to receive the cancellation request. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$L_MS_RQSTID This longword field contains a user-supplied longword message code.

Message Buffer Format for OPC$_RQ_REPLY


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_REPLY.
Reserved This 1-byte field is reserved for future use.
OPC$W_MS_STATUS This 2-byte field contains the low-order word of the longword condition value that $SNDOPR returns in the mailbox specified by the chan argument. You can find a list of these longword condition values under Condition Values Returned in the Mailbox. To test the completion status, you need to extract the low-order word from the longword condition value and compare it to the contents of the OPC$W_MS_STATUS field.
OPC$L_MS_RPLYID This 4-byte field contains a user-supplied message code.
OPC$W_MS_OUNIT This 2-byte field contains the unit number of the terminal to which the operator reply is to be sent. To obtain the unit number of the terminal, you can call $GETDVI, specifying the DVI$_FULLDEVNAM item code. The information returned will consist of the node name and device name as a padded string. Because the unit number is found on the tail end of the string, you must parse the string. One way to do this is, starting from the tail end, to search for the first alphabetic character; the digits to the right of this alphabetic character constitute the unit number.

After extracting the unit number, count the remaining characters in the string. Then, construct a counted ASCII string and use this for the following field, OPC$T_MS_ONAME.

OPC$T_MS_ONAME This variable-length field contains a counted ASCII string specifying the device name of the terminal that is to receive the operator reply. The maximum total length of the string is 14 bytes. See the preceding field description (OPC$W_MS_OUNIT) to learn how to obtain the device name.
OPC$L_MS_OTEXT This variable-length field contains an ASCII string specifying operator-written text to be sent to the user terminal. The length of the string must be in the range 0 to 255 bytes. This field is optional.

Message Buffer Format for OPC$_RQ_TERME


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_TERME.
OPC$Z_MS_ENAB_TERMINALS This 3-byte field contains a user-supplied value. The value 0 indicates that the specified terminal is to be disabled for the specified operator classes. Any nonzero value indicates that the specified terminal is to be enabled for the specified operator classes.
OPC$B_MS_MASK This 4-byte field contains a 4-byte bit vector that specifies which operator terminal types are to be enabled or disabled for the specified terminal. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$W_MS_OUNIT This 2-byte field contains the unit number of the operator terminal to be enabled or disabled for the specified operator terminal types. To obtain the unit number of the terminal, you can call $GETDVI, specifying the DVI$_FULLDEVNAM item code. The information returned will consist of the node name and device name as a padded string. Because the unit number is found on the tail end of the string, you must parse the string. One way to do this is, starting from the tail end, to search for the first alphabetic character; the digits to the right of this alphabetic character constitute the unit number.

After extracting the unit number, count the remaining characters in the string. Then, construct a counted ASCII string and use this for the following field, OPC$T_MS_ONAME.

OPC$T_MS_ONAME This variable-length field contains a counted ASCII string specifying the device name of the operator terminal to be enabled or disabled for the specified operator terminal types. The maximum total length of the string is 16 bytes. See the preceding field description (OPC$W_MS_OUNIT) to learn how to obtain the device name.

Message Buffer Format for OPC$_RQ_STATUS


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_STATUS.
Reserved This 3-byte field is reserved for future use.
Reserved This 4-byte field is reserved for future use.
OPC$W_MS_OUNIT This 2-byte field contains the unit number of the operator terminal whose status is to be requested. To obtain the unit number of the terminal, you can call $GETDVI, specifying the DVI$_FULLDEVNAM item code. The information returned will consist of the node name and device name as a padded string. Because the unit number is found on the tail end of the string, you must parse the string. One way to do this is, starting from the tail end, to search for the first alphabetic character; the digits to the right of this alphabetic character constitute the unit number.

After extracting the unit number, count the remaining characters in the string. Then, construct a counted ASCII string and use this for the following field, OPC$T_MS_ONAME.

OPC$T_MS_ONAME This variable-length field contains a counted ASCII string specifying the device name of the operator terminal whose status is requested. The maximum total length of the string is 14 bytes. See the preceding field description (OPC$W_MS_OUNIT) to learn how to obtain the device name.

Message Buffer Format for OPC$_RQ_LOGI


OPC$B_MS_TYPE This 1-byte field contains the request code OPC$_RQ_LOGI.
OPC$Z_MS_TARGET_CLASSES This 3-byte field contains a 24-bit bit vector that specifies which operator terminal types are to receive the cancellation request. The $OPCDEF macro defines symbolic names for the operator terminal types. You construct the bit vector by specifying the desired symbolic names in a logical OR operation. Following is the symbolic name of each operator terminal type:
OPC$M_NM_CARDS Card device operator
OPC$M_NM_CENTRL Central operator
OPC$M_NM_SECURITY Security operator
OPC$M_NM_CLUSTER OpenVMS Cluster operator
OPC$M_NM_DEVICE Device status information
OPC$M_NM_DISKS Disk operator
OPC$M_NM_NTWORK Network operator
OPC$M_NM_TAPES Tape operator
OPC$M_NM_PRINT Printer operator
OPC$M_NM_OPER1
through
OPC$M_NM_OPER12
System-manager-defined operator functions
OPC$L_MS_RQSTID This longword field contains a user-supplied value.

The value 0 specifies that the current operator log file is to be closed and a new log file opened with all classes enabled (OPC$B_MS_TARGET is ignored).

The value 1 specifies that the current operator log file is to be closed but no new log file is to be opened.

The value 2 specifies that the classes in OPC$B_MS_TARGET are added to the current operator log file classes. A log file is opened if necessary.

The value 3 specifies that the operator classes in OPCB_MS_TARGET are to be removed from the operator log file classes. If all classes are removed, the log file is closed.

OPC$W_MS_OUNIT This 2-byte field contains the unit number of the operator terminal that is making the initialization request. To obtain the unit number of the terminal, you can call $GETDVI, specifying the DVI$_FULLDEVNAM item code. The information returned will consist of the node name and device name as a padded string. Because the unit number is found on the tail end of the string, you must parse the string. One way to do this is, starting from the tail end, to search for the first alphabetic character; the digits to the right of this alphabetic character constitute the unit number.

After extracting the unit number, count the remaining characters in the string. Then, construct a counted ASCII string and use this for the following field, OPC$T_MS_ONAME.

OPC$T_MS_ONAME This variable-length field contains a counted ASCII string specifying the device name of the operator terminal that is making the initialization request. The maximum total length of the string is 14 bytes. See the preceding field description (OPC$W_MS_OUNIT) to learn how to obtain the device name.

chan


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

Channel assigned to the mailbox to which the reply is to be sent. The chan argument is a longword value containing the number of the channel. If you do not specify chan or specify it as the value 0 (the default), no reply is sent.


Previous Next Contents Index