HP OpenVMS Systems Documentation
Content starts here

OpenVMS Utility Routines Manual

Previous Contents Index

SMB$SEND_TO_JOBCTL

The SMB$SEND_TO_JOBCTL routine is used by your symbiont to send messages to the job controller. Three types of messages can be sent: request-completion messages, task-completion messages, and task-status messages.

Format

SMB$SEND_TO_JOBCTL stream [,request] [,accounting] [,checkpoint] [,device_status] [,error]

RETURNS


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

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

stream


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

Stream number specifying the stream to which the message refers. The stream argument is the address of a longword containing the number of the stream to which the message refers.

request


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

Request code identifying the request being completed. The request argument is the address of a longword containing the code that identifies the request that has been completed.

The code usually corresponds to the code the job controller passed to the symbiont by means of a call to SMB$READ_MESSAGE. But the symbiont can also initiate task-completion and task-status messages that are not in response to a request. (See the Description section.)

accounting


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

Accounting information about a task. The accounting argument is the address of a descriptor pointing to the accounting information about a task. Note that this structure is passed by descriptor and not by reference.

The job controller accumulates task statistics into a job-accounting record, which it writes to the accounting file when the job is completed.

The following diagram depicts the contents of the 16-byte structure:

checkpoint


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

Checkpoint data about the currently executing task. The checkpoint argument is the address of the descriptor that points to checkpointing information that relates to the status of a task. When the symbiont sends this information to the job controller, the job controller saves it in the queue database. When a restart-from-checkpoint request is executed for the queue, the job controller retrieves the checkpointing information from the queue database and sends it to the symbiont in the SMBMSG$K_CHECKPOINT_DATA item that accompanies a SMBMSG$K_START_TASK request.

Print symbionts can use the checkpointing information to reposition the input file to the point corresponding to the page being output when the last checkpoint was taken. Other symbionts might use checkpoint information to specify restart information for partially completed tasks.

Note
Because each checkpoint causes information to be written into the job controller's queue database, taking a checkpoint incurs significant overhead. Use caution in regard to the size and frequency of checkpoints. When determining how often to checkpoint, weigh processor and file-system overhead against the convenience of restarting.

device_status


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

Status of the device served by the symbiont. The device_status argument is the address of a longword passed to the job controller, which contains the status of the device to which the symbiont is connected.

This longword contains a longword bit vector, each bit of which specifies device-status information. Each programming language provides an appropriate mechanism for defining these device-status bits. The following table describes each bit:

Device Status Bit Description
SMBMSG$V_LOWERCASE The device to which the symbiont is connected supports lowercase characters.
SMBMSG$V_PAUSE_TASK The symbiont sends this message to inform the job controller that the symbiont has paused on its own initiative.
SMBMSG$V_REMOTE The device is connected to the symbiont by means of a modem.
SMBMSG$V_SERVER The symbiont is not connected to a device.
SMBMSG$V_STALLED Symbiont processing is temporarily stalled.
SMBMSG$V_STOP_STREAM The symbiont requests that the job controller stop the queue.
SMBMSG$V_TERMINAL The symbiont is connected to a terminal.
SMBMSG$V_UNAVAILABLE The device to which the symbiont is connected is not available.

error


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

Condition codes returned by the requested task. The error argument is the address of a vector of longword condition codes. The first longword contains the number of longwords following it.

If the low bit of the first condition code is clear, the job controller aborts further processing of the job. Output of any remaining files, copies of files, or copies of the job is canceled. In addition, the job controller saves up to three condition values in the queue database. The first condition value is included in the job-accounting record that is written to the system's accounting file (SYS$MANAGER:ACCOUNTNG.DAT).

Description

The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages to the job controller.

Most messages the symbiont sends to the job controller are responses to requests made by the job controller. These responses inform the job controller that the request has been completed, either successfully or with an error. When the symbiont sends the message, it usually indicates that the request has been completed.

In such messages, the request argument corresponds to the function code of the request that has been completed. Thus, if the job controller sends a request using the SMBMSG$K_START_TASK code, the symbiont responds by sending a SMB$SEND_TO_JOBCTL message using SMBMSG$K_START_TASK as the request argument.

The responses to some requests use additional arguments to send more information in addition to the request code. The following table shows which additional arguments are allowed in response to each different request:

Request Arguments
SMBMSG$K_START_STREAM request
  device_status
  error
SMBMSG$K_STOP_STREAM request
SMBMSG$K_RESET_STREAM request
SMBMSG$K_START_TASK request
SMBMSG$K_PAUSE_TASK request
SMBMSG$K_RESUME_TASK request
SMBMSG$K_STOP_TASK request
  error 1
1This is usually the value specified in the SMBMSG$K_STOP_CONDITION item that was sent by the job controller with the SMBMSG$K_STOP_TASK request.

In addition to responding to requests from the job controller, the symbiont can send other messages to the job controller. If the symbiont sends a message that is not a response to a request, it uses either the SMBMSG$K_TASK_COMPLETE or SMBMSG$K_TASK_STATUS code. Following are the additional arguments that you can use with the messages identified by these codes:

Code Arguments
SMBMSG$K_TASK_COMPLETE request
  accounting
  error
SMBMSG$K_TASK_STATUS request
  checkpoint
  device_status

The symbiont uses the SMBMSG$K_TASK_STATUS message to update the job controller on the status of a task during the processing of that task. The checkpoint information passed to the job controller with this message permits the job controller to restart an interrupted task from an appropriate point. The device-status information permits the symbiont to report changes in device's status (device stalled, for example).

The symbiont can use the SMBMSG$K_TASK_STATUS message to request that the job controller send a stop-stream request. It does this by setting the stop-stream bit in the device-status argument.

The symbiont can also use the SMBMSG$K_TASK_STATUS message to notify the job controller that the symbiont has paused in processing a task. It does so by setting the pause-task bit in the device-status argument.

The symbiont uses the SMBMSG$K_TASK_COMPLETE message to signal the completion of a task. Note that, when the symbiont receives a START_TASK request, it responds by sending a SMB$SEND_TO_JOBCTL message with SMBSMG$K_START_TASK as the request argument. This response means that the symbiont has started the task; it does not mean the task has been completed. When the symbiont has completed a task, it sends a SMB$SEND_TO_JOBCTL message with SMBMSG$K_TASK_COMPLETE as the request argument.

Optionally, the symbiont can specify accounting information when sending a task-completion message. The accounting statistics accumulate to give a total for the job when the job is completed.

Also, if the symbiont is aborting the task because of a symbiont-detected error, you can specify up to three condition values in the error argument. Aborting a task causes the remainder of the job to be aborted.

Condition Values Returned

SS$_NORMAL Normal successful completion.

This routine also returns any condition value returned by the $QIO system service and the LIB$GET_VM routine.

Chapter 19
Sort/Merge (SOR) Routines

The Sort/Merge (SOR) routines allow you to integrate a sort or merge operation into a program application. Using these callable routines, you can process records, sort or merge them, and then process them again.

19.1 High-Performance Sort/Merge (Alpha Only)

You can also choose the high-performance Sort/Merge utility. This utility takes advantage of the Alpha architecture to provide better performance for most sort and merge operations.

In addition, the high-performance Sort/Merge utility can increase performance by using threads to take advantage of multiple processors on an SMP configured system. Refer to Section 19.1.2 for further information about using threads.

The high-performance Sort/Merge utility supports a subset of the SOR routines. Any differences between the high-performance Sort/Merge utility and Sort/Merge utility (SORT/MERGE) are noted within this chapter.

Note
Memory allocation differences may limit the high-performance Sort/Merge utility's ability to perform the same number of concurrent sort operations as the Sort/Merge utility can perform in the same amount of virtual memory.

If this situation occurs, you can either increase the amount of virtual memory that is available to the process, or reduce the working set extent. For information on using system parameters to change the amount of virtual memory or reduce the working set extent, refer to the OpenVMS System Management Utilities Reference Manual.

.

Use the SORTSHR logical name to select the high-performance Sort/Merge utility. Define SORTSHR to point to the high-performance sort executable in SYS$LIBRARY as follows: 


$ define sortshr sys$library:hypersort.exe

To return to SORT/MERGE, deassign SORTSHR. The Sort/Merge utility is the default if SORTSHR is not defined.

19.1.1 High-Performance SOR Routine Behavior

The behavior of the SOR routines for the high-performance Sort/Merge utility is the same as for SORT/MERGE except as shown in Table 19-1.

If you attempt to use an unsupported capability, the high-performance Sort/Merge utility generates an error. The high-performance Sort/Merge utility adds the following condition value to those listed for SORT/MERGE:

SOR$_NYI Attempt to use a feature that is not yet implemented.

Table 19-1 High-Performance Sort/Merge: Differences in SOR$ Routine Behavior
Feature High-Performance Sort/Merge Behavior
Work files Permissible values of the SOR$BEGIN_SORT work_files argument range from 1 through 255. By default, the high-performance Sort/Merge utility creates two temporary work files.
Input file size If you do not specify an input file size in the SOR$BEGIN_SORT file_alloc argument, the high-performance Sort/Merge utility determines a default based on the size of the input file, or if input is not from files, on available memory.
Specification files The SOR$SPEC_FILE routine is not supported. (Implementation of this feature is deferred to a future OpenVMS Alpha release.)
Key data types DSC$K_DTYPE_O, DSC$K_DTYPE_OU, DSC$K_DTYPE_H, and DSC$K_DTYPE_NZ are not valid key data types in the SOR$BEGIN_MERGE or SOR$BEGIN_SORT key_buffer argument. (Implementation of this feature is deferred to a future OpenVMS Alpha release.)
Key data types not normally supported by SORT/MERGE The SOR$DTYPE routine is not supported. (Implementation of this feature is deferred to a future OpenVMS Alpha release.) Data types that would otherwise be specified using SOR$DTYPE include extended data types and the National Character Set (NCS) collating sequences.
Internal sorting processes Only the record sort process is supported. You can specify the SOR$BEGIN_SORT routine sort_process argument as SOR$GK_RECORD or omit the argument. The SOR$GK_TAG, SOR$GK_ADDRESS, and SOR$GK_INDEX values are not supported for the sort_process argument. (Implementation of this feature is deferred to a future OpenVMS Alpha release.)
Statistical summary information The following statistics are currently supported:
Records read/input (SOR$K_REC_INP)
Records sorted (SOR$K_REC_SOR)
Records output (SOR$K_REC_OUT)
Input record length (SOR$K_LRL_INP)

The following statistics are currently unavailable:

Internal length
Output record length
Sort tree size
Number of initial runs
Maximum merge order
Number of merge passes
Work file allocation

Full implementation of this feature is deferred to a future OpenVMS Alpha release.

User-supplied action routines The following user-supplied action routines are not supported for either SOR$BEGIN_MERGE or SOR$BEGIN_SORT. (Implementation of this feature is deferred to a future OpenVMS Alpha release.) You must provide a placeholder comma (,) in the argument list if other arguments follow the customary position of the user_compare or user_equal argument.
user_compare Compares records to determine their sort or merge order.
user_equal Resolves the sort or merge order when records have duplicate keys.

19.1.2 Using Threads with High-Performance Sort/Merge

The high-performance Sort/Merge utility can take advantage of multiple processors on an SMP configured system by using threads to gain additional performance. Threads use is optimized under the following conditions:

  • the SYSGEN parameter MULTITHREAD is set to the number of CPUs on the system
  • the base image of the application using the high-performance Sort/Merge utility is linked with the /THREADS_ENABLE qualifier

When linking an executable image that uses the high-performance Sort/Merge utility, the executable should be linked with the /THREADS_ENABLE linker qualifier. Either /THREADS_ENABLE or /THREADS_ENABLE=(MULTIPLE_KERNEL_THREADS,UPCALLS) qualifiers may be used. (Refer to the Guide to DECthreads manual in the OpenVMS documentation set for more information on this linker qualifier.)

The high-performance Sort/Merge utility will not utilize multiple processors, and therefore won't run at peak performance, if the /THREADS_ENABLE linker qualifier is omitted, explicitly disabled (by the /NOTHREADS_ENABLED), or partially enabled (by the /THREADS_ENABLE=UPCALLS or /THREADS_ENABLE=MULTIPLE_KERNEL_THREADS). However, the high-performance Sort/Merge utility will still run and produce correct results.

19.2 Introduction to SOR Routines

The following SOR routines are available for use in a sort or merge operation:

Routine Description
SOR$BEGIN_MERGE Sets up key arguments and performs the merge. This is the only routine unique to MERGE.
SOR$BEGIN_SORT Initializes the sort operation by passing key information and sort options. This is the only routine unique to SORT.
SOR$DTYPE Defines a key data-type that is not normally supported by SORT/MERGE. (This feature is not currently supported by the high-performance Sort/Merge utility.)
SOR$END_SORT Performs cleanup functions, such as closing files and releasing memory.
SOR$PASS_FILES Passes names of input and output files to SORT or MERGE; must be repeated for each input file.
SOR$RELEASE_REC Passes one input record to SORT or MERGE; must be called once for each record.
SOR$RETURN_REC Returns one sorted or merged record to a program; must be called once for each record.
SOR$SORT_MERGE Sorts the records.
SOR$SPEC_FILE Passes a specification file or specification text. A call to this routine must precede all other calls to the SOR routines. (This feature is not currently supported by the high-performance Sort/Merge utility.)
SOR$STAT Returns a statistic about the sort or merge operation. (This feature is partially supported by the high-performance Sort/Merge utility.)
You can call these SOR routines from any language that supports the OpenVMS calling standard. Note that the application program should declare referenced constants and return status symbols as external symbols; these symbols will be resolved upon linking with the utility shareable image.

After being called, each of these routines performs its function and returns control to a program. It also returns a 32-bit condition code value indicating success or error, which a program can test to determine success or failure conditions.

Previous Next Contents Index