QMGR(1M)

NAME
qmgr - NQS queue manager program

SYNOPSIS
qmgr [ args ]

DESCRIPTION
Qmgr is a program used by the System Administrator or System Operator to control NQS requests, queues, devices, and the general NQS configuration at the local machine. Single commands can be given on the command line, or if there are none, Qmgr enters an interactive session.

  Definitions
An NQS request is a request by a user or user program to perform a function that requires a delay in servicing (e.g., after a certain time). Examples of such functions are the the scheduling of a shared serial-access resource (e.g., a printer), and the scheduling of batch job requests. A device queue holds requests for resources such as printers and Computer Output Microfilm (COM) units. A batch queue holds requests for scheduled, perhaps delayed, processing by various subsystems in the NPSN. A pipe queue is a queue which can pass queued requests on to other pipe queues, batch queues, or device queues. An NQS device is a site at which a shared serial-access resource such as a printer is offered. A daemon is a process which is designed to run continuously, providing some service when needed. (See the QUEUE TYPES section below for more information concerning queues.) Lastly, an NQS manager identifies a person who is capable of changing any NQS characteristic on the local machine. An NQS operator identifies a person who can execute only the operator commands as a proper subset of all the commands provided by the qmgr(1m) utility.

  Commands
The following paragraphs describe the syntax of each Qmgr(1m) command. All command keywords are recognized regardless of upper or lower case usage. Keyword characters shown in uppercase indicate the smallest possible abbreviation of the keyword for the particular command being described.

ABort Queue queue [ seconds ]
    All requests in the named queue that are currently running are aborted as follows. A SIGTERM signal is sent to each process of each request presently running in the named queue. After the specified number of seconds of real time have elapsed, a SIGKILL signal is sent to all remaining processes for each request running in the named queue. If a seconds value is not specified, then the delay is sixty seconds. All requests aborted by this command are deleted, and all output files associated with the requests are returned to the appropriate destination.

    NQS operator privileges are required to use this command.

ADd DEStination = destination queue
ADd DEStination = ( destination [ , destination ... ] ) queue
    The specified destination(s) are added as valid destinations for a pipe queue named queue.

    Full NQS manager privileges are required to use this command.

ADd DEVice = device queue
ADd DEVice = (device [ , device ... ] ) queue
    The specified device(s) are added as resources to service requests from queue. The device(s) must exist (see Create DEVICE below).

    Full NQS manager privileges are required to use this command.

ADd Forms form-name ...
    The specified form-name(s) are added to the list of valid forms.

    Full NQS manager privileges are required to use this command.

ADd Groups = group queue
ADd Groups = ( group [ , group ... ] ) queue
    The specified group(s) are added to the access list for queue. There are two ways to specify a group:

        group name
        [group id]

    Full NQS manager privileges are required to use this command.

ADd Managers manager ...
    The specified manager(s) are added to the list of authorized NQS managers with privileges as specified. A manager specification consists of an account name specification, followed by a colon, followed by either the letter m or the letter o. There are four ways to specify an account name:

        local_account_name
        [local_user_id]
        [remote_user_id]@remote_machine_name
        [remote_user_id]@[remote_machine_mid]

    If the account name specification is followed by :m, then the account is designated as an NQS manager account, capable of using all qmgr commands. If the account name specification is followed by :o, then the account is designated as an NQS operator account, capable of only using those commands appropriate for an NQS operator.

    Full NQS manager privileges are required to use this command.

ADd Queues = ( queue [ , queue ... ] ) complex
    Add the specified queue(s) to the batch queue complex named complex.

    Full NQS manager privileges are required to use this command.

ADd Users = user queue
ADd Users = ( user  [ , user ... ] ) queue
    The specified user(s) are added to the access list for queue. There are two ways to specify a user:

        user name
        [user id]

    Full NQS manager privileges are required to use this command.

Create Batch_queue queue [ PRiority = n ]
    [ PIpeonly ] [ Run_limit = n ] [ User_limit = n ]
    Define a batch queue named queue with inter-queue priority n (0..63). If not specified, the default is 16. If PIpeonly is specified, then requests may enter this queue only if their source is a pipe queue. The specification of a Run_limit sets a ceiling on the maximum number of requests allowed to run in the batch queue at any given time. The default run-limit is one. The specification of a User_limit sets a limit on the maximum number of requests allowed to run in the batch queue at any given time by a particular user. The default user-limit is one. (See the QUEUE TYPES section below for more information.)

    Full NQS manager privileges are required to use this command.

Create Complex = ( queue [ , queue ... ] ) complex Create a queue
    complex consisting of the specified set of batch queues. NQS provides for the grouping of a set of batch queues into a queue complex which can have an associated Run_limit and User_limit. Both of these limits default to 1.

    Full NQS manager privileges are required to use this command.

Create DEVICE device FOrms = forms FUllname = filename
    Server = ( server )
    Define a device with the specified forms and associate it with a server. This is done by specifying an absolute path name to the program binary (server) and any arguments required by the program. Filename is the absolute path name of the device (special file) and is typically /dev/device.

    Full NQS manager privileges are required to use this command.

Create DEVICE_queue queue PRiority = n [ Device = device ]
    [ Device = ( device [ , device ... ] ) ]
    [ PIpeonly ]
    Define a device queue named queue with inter-queue priority n (0..63). If PIpeonly is specified, then requests may enter this queue only if their source is a pipe queue. After Device appears a list of one or more devices that may service this queue. (See the QUEUE TYPES section below for more information.)

    Full NQS manager privileges are required to use this command.

Create Pipe_queue queue
    [ PRiority = n ] [ Server = ( server ) ] [ Destination = destination ]
    [ Destination = ( destination [ , destination ... ] ) ]
    [ PIpeonly ] [ Run_limit = n ] [ LB_Out ] [ LB_In ]
    Define a pipe queue named queue with inter-queue priority n (0..63) and associate it with a server. This is done by specifying an absolute path name to the program binary (server) and any arguments required by the program. If not specified, the default priority is 16, and the default server is NQS_LIB/pipeclient. After Destination appears a list of one or more destination queues that requests from this pipe queue may be sent to. If PIpeonly is specified, then requests may enter this queue only if their source is a pipe queue. Run_limit sets a ceiling on the maximum number of requests allowed to run in the pipe queue at any given time. The default run-limit is one. (See the QUEUE TYPES section below for more information.) If LB_Out is specified, the queue will load balance outbound by choosing the destination using information about the load on the various destination nodes, if available, or by using a round-robin algorithm if not. Otherwise, one destination in the list will always be chosen and the others ignored. If LB_In is specified, the queue will accept a request only if it can be run immediately in one of its destination queues. Otherwise, the queue will accept all requests, even if they must wait before they can run. (See the LOAD BALANCING section below for more information.)

    Full NQS manager privileges are required to use this command.

DElete Complex complex
    Delete a queue complex.

    Full NQS manager privileges are required to use this command.

DElete DEStination = destination queue
DElete DEStination = ( destination [ , destination ... ] )  queue
    Delete the mappings from the pipe queue queue to the destination queues. All requests from the named queue being transferred to a deleted destination complete normally. If all destinations for a pipe queue are deleted in this manner, then the pipe queue is effectively stopped.

    Full NQS manager privileges are required to use this command.

DElete DEVice device
    Delete the specified device. A device must be disabled to delete it from the device set (see DIsable Device below).

    Full NQS manager privileges are required to use this command.

DElete DEVice = device queue
DElete DEVice = ( device [ , device ... ] ) queue
    Delete the mappings from the device queue queue to the device(s). All requests from the named device queue running on any of the named devices are allowed to complete normally. If ALL queue-to-device mappings for the named device queue are removed by this command, then the queue is effectively stopped.

    Full NQS manager privileges are required to use this command.

DElete Forms form-name ...
    The specified form-name(s) are deleted from the list of valid forms.

    Full NQS manager privileges are required to use this command.

DElete Groups = group queue
DElete Groups = ( group  [ , group ... ] )
    queue
    The specified group(s) are deleted from the access list for queue. There are two ways to specify a group:

        group name
        [group id]

    Full NQS manager privileges are required to use this command.

DElete Managers manager ...
    The specified manager(s) are deleted from the list of authorized NQS managers. A manager specification consists of an account name specification, followed by a colon, followed by either the letter m or the letter o. There are four ways to specify an account name:

        local_account_name
        [local_user_id]
        [remote_user_id]@remote_machine_name
        [remote_user_id]@[remote_machine_mid]

    If the account name specification is followed by :m, it is understood that the account is currently permitted to use all qmgr commands. If the account name specification is followed by :o, it is understood that the account is currently permitted to use only those commands appropriate for an operator to use. The root account always has full privileges.

    Full NQS manager privileges are required to use this command.

DElete Queue queue
    The queue is deleted. To delete a queue, no requests may be present in the queue and the queue MUST be disabled (see DIsable Queue below). Any queue-to-device mappings are updated accordingly.

    If the queue is a destination for a pipe queue, then the queue must be manually deleted as a destination for that pipe queue (see DElete DEStination above).

    Full NQS manager privileges are required to use this command.

DElete Users = user queue
DElete Users = ( user   [ , user ... ] ) queue
    The specified user(s) are deleted from the access list for queue. There are two ways to specify a user:

        user name
        [user id]

    Full NQS manager privileges are required to use this command.

DIsable Device device
    The current request will complete. After that, the device is prevented from handling any more requests until it is enabled (see ENable Device below). If the disabled device was the last enabled device in a queue-to-device mapping, then the device queue is effectively stopped.

    NQS operator privileges are required to use this command.

DIsable Queue queue
    Prevent any more requests from being placed in this queue.

    NQS operator privileges are required to use this command.

ENable Device device
    If the device is already enabled, then this is a no-op. Otherwise, the device becomes available to handle requests.

    NQS operator privileges are required to use this command.

ENable Queue queue
    If the queue is already enabled, then this is a no-op. Otherwise, the queue is enabled to accept new requests.

    NQS operator privileges are required to use this command.

EXit
    Exit from the NQS manager subsystem.

Help [ command ]
    Get help information. Help without an argument displays information about what commands are available. Help with an argument displays information about that command. The command may be partially specified as long as it is unique. A more complete help request yields more detailed information.

    The Help command provides information that is often more extensive than the command descriptions in this manual page! Use it.

Hold request requestid
    The indicated request is put on hold. Queued and waiting requests become ineligible for processing. Requests in any other state are unaffected.

    Requests can be made eligible for processing again by use of the RELease Request command.

    NQS operator privileges are required to use this command.

Lock Local_daemon
    Lock the NQS local daemon into memory. See plock(2).

    NQS operator privileges are required to use this command.

MEmdump option
    Dump the appropriate internal NQS information to the log file. The available options are LOAD to print load information, and REQ to print the list of requests on the system. This command is used primarily for debugging purposes. No validation of the option is done. Other options may be added in the future.

    NQS operator privileges are required to use this command.

MODify Request requestid
    [ Nice_limit = nice ] [ RTime_limit = Tlimit ] [ RMemory_limit = Mlimit ]
    Modify parameters for the request specified by requestid. Nice is the initial nice value for the request. Tlimit is a per request CPU time limit. Mlimit is a per request memory limit. For the syntax of these limits, see the LIMITS section below.

    NQS operator privileges are required to use this command.

MOVe Queue queue1 queue2
    Move all requests currently in queue1 to queue2.

    NQS operator privileges are required to use this command.

MOVe Request = (requestid ...) queue
    Move the request(s) named by the requestid(s) to the named queue. It is only possible to move queued and waiting requests.

    NQS operator privileges are required to use this command.

Purge Queue queue
    All queued requests are purged (dropped) from the queue and are irretrievably lost. Running requests in the queue are allowed to complete.

    NQS operator privileges are required to use this command.

Quit
    Exit from the NQS manager subsystem.

RELease Request requestid
    The indicated request is released and is made available for scheduling.

    NQS operator privileges are required to use this command.

REMove Queue = ( queue [ , queue ... ] ) complex
    Remove the specified queue(s) from the batch queue complex named complex.

    Full NQS manager privileges are required to use this command.

SEt COMplex Run_limit = run-limit complex
    Change the run-limit of an NQS queue complex. The run-limit determines the maximum number of requests that will be allowed to run in the queue complex at any given time.

    NQS operator privileges are required to use this command.

SEt COMplex User_limit = user-limit complex
    Change the user-limit of an NQS queue complex. The user-limit determines the maximum number of requests that will be allowed to run in the queue complex at any given time by a single user.

    NQS operator privileges are required to use this command.

SEt CORefile_limit = ( limit ) queue
    Set a per-process maximum core file size limit for a batch queue against which the per-process maximum core file size limit for a request may be compared. If the local host does not support per-process core file size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum core file size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process core file size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt DAta_limit = ( limit ) queue
    Set a per-process maximum data segment size limit for a batch queue against which the per-process maximum data segment size limit for a request may be compared. If the local host does not support per-process data segment size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum data segment size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum data segment size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt DEBug level
    Set the debug level. The following values are valid:

        0   No debug
        1   Minimum debug
        2   More debug
        3   Mondo debug

    Full NQS manager privileges are required to use this command.

SEt DEFault Batch_request Priority priority
    Set the default intra-batch-queue priority. This is NOT the UNIX execution time priority. This is the priority used if the user does not specify an intra-queue priority parameter on the qsub(1) command. Valid priorities are 0 through 63, inclusive.

    Full NQS manager privileges are required to use this command.

SEt DEFault Batch_request Queue queue
    Set the default batch queue. This is the queue used if the user does not specify a queue parameter on the qsub(1) command.

    Full NQS manager privileges are required to use this command.

SEt DEFault DEStination_retry Time retry_time
    Set the default number of hours that can elapse during which time a pipe queue destination can be unreachable, before being marked as completely failed.

    Full NQS manager privileges are required to use this command.

SEt DEFault DEStination_retry Wait interval
    Set the default number of minutes to wait before retrying a pipe queue destination that was unreachable at the time of the last attempt.

    Full NQS manager privileges are required to use this command.

SEt DEFault DEVice_request Priority priority
    Set the default intra-device-queue priority. This is the priority used if the user does not specify an intra-queue priority parameter on the qpr(1) command.

    Full NQS manager privileges are required to use this command.

SEt DEFault Load_interval interval
    Set the default number of minutes between reports to the NQS scheduler. This parameter is only operational if a scheduler has been configured (see SEt Scheduler below).

    Full NQS manager privileges are required to use this command.

SEt DEFault Print_request Forms form-name
    Set the default print forms to form-name. This is the forms used if the user does not specify a forms parameter on the qpr(1) command.

    Full NQS manager privileges are required to use this command.

SEt DEFault Print_request Queue queue
    Set the default print queue. This is the queue used if the user does not specify a queue parameter on the qpr(1) command.

    Full NQS manager privileges are required to use this command.

SEt DEStination = destination queue
SEt DEStination = ( destination [ , destination ... ] ) queue
    Associate one or more destination queues with a particular pipe queue.

    Full NQS manager privileges are required to use this command.

SEt DEVICE = device queue
SEt DEVICE = ( device [ , device ... ] ) queue
    Associate one or more devices with a particular queue.

    Full NQS manager privileges are required to use this command.

SEt DEVICE_server = ( server ) device
    Associate a server with a device. Server should consist of the absolute path name to the program binary followed by any arguments required by the program.

    Full NQS manager privileges are required to use this command.

SEt Echo
    Causes Qmgr to echo commands entered at the command prompt. The primary value is to get the Qmgr commands into a log file.

SEt Forms form-name ...
    Specify the valid form-name(s). Other valid forms may be added to this list (see ADd Forms above).

    Full NQS manager privileges are required to use this command.

SEt Forms = form-name device
    Set the form-name for a device.

    Full NQS manager privileges are required to use this command.

SEt Global Batch_limit    = integer-limit
    Change the number of batch jobs that can run in all the queues at the same time.

    NQS manager privileges are required to use this command.

SEt Global Pipe_limit  = integer-limit
    Change the number of jobs that can be processed in all the pipe queues at the same time.

    NQS manager privileges are required to use this command.

SEt LB_In queue
    Specify that the pipe queue will accept requests only if one of its destination queues can immediately run the request after considering run, user and queue complex limits.

    Full NQS manager privileges are required to use this command.

SEt LB_Out queue
    Specify that the pipe queue will distribute requests to the destination queues according to available load information or to a round robin algorithm. The default is to always use the same destination in the list until it becomes disabled.

    Full NQS manager privileges are required to use this command.

SEt LIfetime lifetime
    Set pipe-queue request lifetime in hours.

    Full NQS manager privileges are required to use this command.

SEt LOAd_daemon = ( daemon )
    Specify the load daemon to be used. Daemon should consist of the absolute path name of the daemon followed by any arguments required by the daemon.

    Full NQS manager privileges are required to use this command.

SEt LOG_file filename
    Specify the name of the log file for NQS messages. Note that the underscore is required.

    Full NQS manager privileges are required to use this command.

SEt MAIl userid
    Specify the userid used to send NQS mail.

    Full NQS manager privileges are required to use this command.

SEt MANagers manager ...
    The list of authorized NQS managers is set to the specified manager(s). If there is more than one manager in the list, separate with spaces. A manager specification consists of an account name specification, followed by a colon, followed by either the letter m or the letter o. There are four ways to specify an account name:

        local_account_name
        [local_user_id]
        [remote_user_id]@remote_machine_name
        [remote_user_id]@[remote_machine_mid]

    If the account name specification is followed by :m, then the account is designated as an NQS manager account, capable of using all qmgr commands. If the account name specification is followed by :o, then the account is designated as an NQS operator account, capable of only using those commands appropriate for an NQS operator. The root account always has full privileges. Also see ADd Manager above.

    Full NQS manager privileges are required to use this command.

SEt MAXimum Copies copies
    Set the maximum number of print copies.

    Full NQS manager privileges are required to use this command.

SEt MAXimum Open_retries retries
    Specify the maximum number of retries for a failed device open.

    Full NQS manager privileges are required to use this command.

SEt MAXimum Print_size size
    Specify the maximum size of an NQS print file in bytes.

    Full NQS manager privileges are required to use this command.

SEt NEtwork Client = ( client )
    Specify the network client to be used. Client should consist of the absolute path name of the client followed by any arguments required by the client.

    Full NQS manager privileges are required to use this command.

SEt NEtwork Daemon = ( daemon )
    Specify the network daemon to be used. Daemon should consist of the absolute path name of the daemon followed by any arguments required by the daemon.

    Full NQS manager privileges are required to use this command.

SEt NEtwork Server = ( server )
    Specify the network server to be used. Server should consist of the absolute path name of the server followed by any arguments required by the server.

    Full NQS manager privileges are required to use this command.

SEt NDP= priority queue
    Change the non-degrading priority of an NQS batch queue. The NPD priority determines the non-degrading priority that jobs running in the queue will have. The minimum non-degrading priority is 128 and the maximum is 254. Higher values cause entries in that queue to run at a lower priority. This command only applies to Silicon Graphics 4D series of computers.

    Full NQS manager privileges are required to use this command.

SEt NIce_value_limit = nice-value queue
    Set the UNIX nice-value limit for a batch queue, against which the nice-value for a request may be compared. If a request already in the queue has asked for treatment more favorable than the new nice-value, then it will be given a grandfather clause. A request specifying a nice-value may only enter a batch queue if the queue's nice value is numerically less than (more willing to allow access to the CPU) or equal to the request's nice value. Nice-value is an integer preceded by an optional negative sign.

    For machines running AIX, only, if the nice-value for a queue is set to numerically greater than 15, then the priority is set according to the formula:

        priority = 106 + nice

    This will make NQS batch jobs run at a lower priority than interactive jobs. This may not be desirable if there are compute bound interactive jobs. These will prevent batch jobs in this queue from running. Since the NQS shepherd will be running at the same priority, it will not respond quickly in this circumstance to a Qdel request. Full NQS manager privileges are required to use this command.

SEt NO_Access queue
    Specify that no one will be allowed to place requests in queue. Root is an exception; requests submitted by root are always allowed into a queue, even if root is not explicitly given access.

    Full NQS manager privileges are required to use this command.

SEt NO_Default Batch_request Queue
    Indicate that there is to be no default batch request queue.

    Full NQS manager privileges are required to use this command.

SEt NO_Default Print_request Forms
    Indicate that there is to be no default print request forms.

    Full NQS manager privileges are required to use this command.

SEt NO_Default Print_request Queue
    Indicate that there is to be no default print request queue.

    Full NQS manager privileges are required to use this command.

SEt NO_LB_In queue
    Specify that the pipe queue will always accept requests even if the request will not be able to run immediately in the destination queue.

    Full NQS manager privileges are required to use this command.

SEt NO_LB_Out queue
    Specify that the pipe queue will always send requests to one of the destinations in its list and ignore load balancing considerations.

    Full NQS manager privileges are required to use this command.

SEt NO_LOad_daemon
    Indicate that there is to be no load daemon.

    Full NQS manager privileges are required to use this command.

SEt NO_Network_daemon
    Indicate that there is to be no network daemon.

    Full NQS manager privileges are required to use this command.

SEt NO_Pipeonly queue
    Specify that the queue will accept request from pipe queues or directly from a qsub command. This is the default.

    Full NQS manager privileges are required to use this command.

SEt NO_Scheduler
    Indicate that there is to be no NQS scheduler. This stops the NQS load daemon if it is running.

    Full NQS manager privileges are required to use this command.

SEt Open_wait interval
    Specify the number of seconds to wait between failed device opens.

    Full NQS manager privileges are required to use this command.

SEt PER_Process Cpu_limit = ( limit ) queue
    Set a per-process maximum CPU time limit for a batch queue against which the per-process maximum CPU time limit for a request may be compared. If the local host does not support per-process CPU time limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum CPU time limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum CPU time limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Process Memory_limit = ( limit ) queue
    Set a per-process maximum memory size limit for a batch queue against which the per-process maximum memory size limit for a request may be compared. If the local host does not support per-process memory size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum memory size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum memory size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Process Permfile_limit = ( limit ) queue
    Set a per-process maximum permanent file size limit for a batch queue against which the per-process maximum permanent file size limit for a request may be compared. If the local host does not support per-process permanent file size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum permanent file size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum permanent file size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Process Tempfile_limit = ( limit ) queue
    Set a per-process maximum temporary file size limit for a batch queue against which the per-process maximum temporary file size limit for a request may be compared. If the local host does not support per-process temporary file size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum temporary file size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum temporary file size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Request Cpu_limit = ( limit ) queue
    Set a per-request maximum CPU time limit for a batch queue against which the per-request maximum CPU time limit for a request may be compared. If the local host does not support per-request CPU time limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-request maximum CPU time limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-request maximum CPU time limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Request Memory_limit = ( limit ) queue
    Set a per-request maximum memory size limit for a batch queue against which the per-request maximum memory size limit for a request may be compared. If the local host does not support per-request memory size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-request maximum memory size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-request maximum memory size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Request Permfile_limit = ( limit ) queue
    Set a per-request maximum permanent file space limit for a batch queue against which the per-request maximum permanent file space limit for a request may be compared. If the local host does not support per-request permanent file space limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-request maximum permanent file space limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-request maximum permanent file space limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PER_Request Tempfile_limit = ( limit ) queue
    Set a per-request maximum temporary file space limit for a batch queue against which the per-request maximum temporary file space limit for a request may be compared. If the local host does not support per-request temporary file space limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-request maximum temporary file space limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-request maximum temporary file space limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt PIPE_client = ( client ) queue
    Associate a pipe client with a pipe queue. Client should consist of the absolute path name to the program binary followed by any arguments required by the program. Note that the underscore is required.

    Full NQS manager privileges are required to use this command.

SEt PIPEOnly queue
    Specify that the queue will only accept requests from pipe queues and not directly from a qsub command.

    Full NQS manager privileges are required to use this command.

SEt PRiority =  priority queue
    Specify the inter-queue priority of a queue. Valid priorities are 0 through 63, inclusive.

    Full NQS manager privileges are required to use this command.

SEt Run_limit = run-limit queue
    Change the run-limit of an NQS batch or pipe queue. The run-limit determines the maximum number of requests that will be allowed to run in the queue at any given time.

    NQS operator privileges are required to use this command.

SEt SCheduler system
    Set the NQS scheduler to the indicated system. The scheduler will have job completion messages sent to it, and if a load daemon is running the load messages will be sent to the scheduler node.

    NQS operator privileges are required to use this command.

SEt SErver Available server
    Send a message to the NQS daemon to indicate that the server system is available to receive requests. This command is used when the server is available, but qstat indicates it is not accepting requests.

    NQS operator privileges are required to use this command.

SEt SErver Noperformance server
    Remove the relative performance information for the server from the scheduler's database. The effect is to set the relative performance level to the default, or 1.

    This command has meaning only on the scheduler system, as that is the only system that uses the load and performance information to order destinations for requests.

    NQS Manager privileges are required to use this command.

SEt SErver Performance =  performance server
    Set the relative performance information for the server to the indicated value. Relative performance is an integer between 1 and 1024. The greater the value, the more powerful the machine. The default value is 1.

    The relative performance is linear. This means that a system with a relative performance of 10 is considered twice as fast as a machine with a relative performance of 5.

    This command has meaning only on the scheduler system, as that is the only system that uses the load and performance information to order destinations for requests.

    NQS Manager privileges are required to use this command.

SEt SHell_strategy FIxed = ( shell )
    Specify that shell should be used to execute all batch requests. Shell must be the absolute path name of a command interpreter.

    Full NQS manager privileges are required to use this command.

SEt SHell_strategy FRee
    Specify that the free shell strategy should be used to execute all batch requests. The free shell strategy aims at duplicating the shell choice that would have been made if the batch request script had been executed interactively. Under this strategy, the user's login shell is allowed to determine the shell to be used to execute the batch request. The user's login shell is the shell named within the user's entry in the password file (see passwd(4)).

    Full NQS manager privileges are required to use this command.

SEt SHell_strategy Login
    Specify that the login shell strategy should be used to execute all batch requests. Under the login shell strategy, the user's login shell is used to execute the batch request. The login shell is the shell named in the password file (see passwd(4)).

    Full NQS manager privileges are required to use this command.

SEt STack_limit = ( limit ) queue
    Set a per-process maximum stack segment size limit for a batch queue against which the per-process maximum stack segment size limit for a request may be compared. If the local host does not support per-process stack segment size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum stack segment size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum stack segment size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SEt UNrestricted_access queue
    Specify that no requests will be turned away from queue on the grounds of queue access restrictions.

    Full NQS manager privileges are required to use this command.

SEt USer_limit = user-limit queue
    Change the user run-limit of an NQS batch or pipe queue. The user-limit determines the maximum number of requests that will be allowed to run in the queue at any given time by a particular user.

    NQS operator privileges are required to use this command.

SEt Working_set_limit = ( limit ) queue
    Set a per-process maximum working set size limit for a batch queue against which the per-process maximum working set size limit for a request may be compared. If the local host does not support per-process working set size limits, then this command will report an error. Otherwise, every batch queue on the local host will have a per-process maximum working set size limit associated with it at all times. If a request already in the queue has asked for more than the new limit, then it will be given a grandfather clause. A request specifying a per-process maximum working set size limit may only enter a batch queue if the queue's limit is greater than or equal to the request's limit. For the syntax of limit, see the LIMITS section below.

    Full NQS manager privileges are required to use this command.

SHOw All
    Display the standard amount of information about devices, forms, limits supported, managers, parameters, and queues. See below.

SHOw Device [ device-name ]
    Display the status of all NQS devices on this host. If a device-name is specified, output will be limited to that device.

SHOw Forms
    Display the list of valid forms.

SHOw LImits_supported
    Display the list of NQS resource limit types which are meaningful on this machine. If a limit type is meaningful on a machine, then the corresponding qmgr(1M) commands will allow the association of a limit of that type with any batch queue on that machine. Note that users may request resource limits that are NOT meaningful on the machine where qsub(1) is invoked. If the the request is to be executed on a remote machine where the limit is meaningful, then NQS will honor it. Otherwise the unsupported limit is simply ignored.

SHOw LOng Queue [ queue-name [ user-name ] ]
    Display in long format the status of all NQS queues on this host. If a queue-name is specified, output will be limited to that queue. If a user-name is specified, output will downplay any requests not belonging to that user.

SHOw Managers
    Display the list of authorized NQS managers.

SHOw Parameters
    Display the general NQS parameters.

SHOw Queue [ queue-name [ user-name ] ]
    Display the status of all NQS queues on this host. If a queue-name is specified, output will be limited to that queue. If a user-name is specified, output will downplay any requests not belonging to that user.

SHOw Servers
    Display the list of compute servers and their relative performance values..

SHOw Version
    Display the current Qmgr version.

SHUtdown [ seconds ]
    Shutdown NQS on the local host. A SIGTERM signal is sent to each process of each request presently running. After the specified number of seconds of real time have elapsed, a SIGKILL signal is sent to all remaining processes for each request. If a seconds value is not specified, then the delay is sixty seconds. Unlike ABort Queue, SHUtdown requeues all of the requests it kills, provided that the initial SIGTERM signal is caught or ignored by the running request.

    NQS operator privileges are required to use this command.

SNap File = ( file-specification )
    Specify that a file containing all Qmgr commands necessary to define the current NQS configuration will be written to the indicated file. The default directory is the current working directory unless a full pathname is specified.

    Full NQS manager privileges are required to use this command.

STArt Load_daemon
    This command will start up the load daemon if it is not already running.

    NQS operator privileges are required to use this command.

STArt NEtwork_daemon
    This command will start up the network daemon if it is not already running.

    NQS operator privileges are required to use this command.

STArt NQs
    Startup the NQS system.

    Full NQS manager privileges are required to use this command.

STArt Queue queue
    If the queue is already started, then nothing happens. Otherwise, the queue is started and requests in the queue are eligible for selection.

    NQS operator privileges are required to use this command.

STOp Load_daemon
    If the load daemon is running it will be stopped.

    NQS operator privileges are required to use this command.

STOp Network_daemon
    If the network daemon is running it will be stopped.

    NQS operator privileges are required to use this command.

STOp Queue queue
    Any requests in the queue that are currently running are allowed to complete. All other requests are "frozen" in the queue. New requests can still be submitted to the queue, but will be "frozen" like the other requests in the queue.

    NQS operator privileges are required to use this command.

Unlock Local_daemon
    Remove a lock that has been keeping the NQS local daemon in memory. See plock(2).

    NQS operator privileges are required to use this command.

QUEUE TYPES
NQS supports four different queue types, that serve to provide four very different functions. These four queue types are known as batch, device, pipe, and network.

The queue type of batch can only be used to execute NQS batch requests. Only NQS batch requests created by the qsub(1) command can be placed in a batch queue.

The queue type of device can only be used to execute NQS device requests. Only NQS device requests created by the qpr(1) command can be placed in a device queue.

Queues of type: pipe, are used to send NQS requests to other pipe queues, or to request destination queues of type batch or device, as appropriate for the request type. In general, pipe queues in combination with network queues, act as the mechanism that NQS uses to to transport both batch and device requests to distant queues on other remote machines. It is also perfectly legal for a pipe queue to transport requests to queues on the same machine.

When a pipe queue is defined, it is given a destination set, which defines the set of possible destination queues for requests entered in that pipe queue. In this manner, it is possible for a batch or device request to pass through many pipe queues on its way to its ultimate destination, which must eventually be a queue of type batch or device (matching the request type).

Each pipe queue has an associated server. For each request handled by a pipe queue, the associated server is spawned which must select a queue destination for the request being handled, based on the characteristics of the request, and upon the characteristics of each queue in the destination set defined for the pipe queue.

Since a different server can be configured for each pipe queue, and batch and device queues can be endowed with the pipeonly attribute that will only admit requests queued via another pipe queue, it is possible for respective NQS installations to use pipe queues as a request class mechanism, placing requests that ask for different resource allocations in different queues, each of which can have different associated limits and priorities.

It is also completely possible for a pipe client (pipe queue server) when handling a request, to discover that no destination queue will accept the request, for various reasons which can include insufficient resource limits to execute the request, or a lack of a corresponding account or privilege for queueing at a remote queue. In such circumstances, the request will be deleted, and the user will be notified by mail (see mail(1)).

The queue type of network as alluded to earlier, is implicitly used by pipe queues to pass NQS requests between machines, and is also used to handle queued file transfer operations.

QUEUE ACCESS
NQS supports queue access restrictions. For each queue of queue type other than network, access may be either unrestricted or restricted. If access is unrestricted, any request may enter the queue. If access is restricted, a request can only enter the queue if the requester or the requester's login group has been given access. Requests submitted by root are an exception; they are always queued, even if root has not explicitly been given access.

LOAD BALANCING
NQS supports several levels of load balancing. In the simplest implementation, there is no load balancing. If a pipe queue has serveral destinations, all requests are sent to one of the destinations, ignoring the others, until the favored destination is disabled.

A second level is that a pipe queue can be set up to be load balanced outbound. This means that the destinations will be selected in a sort of round robin algorithm, so that the jobs will be distributed more evenly.

The third level is that the destination pipe queues for a local pipe queue can be set load balanced inbound. This means that it will refuse a request unless it can be run immediately. If none of the destination queues can run the request immediately, it waits on the source machine until one of the destination queues can run the request.

The final level is implemented using the concept of a scheduler, which is new in Version 3.30. A scheduler is a machine designated to distribute jobs to a set of queues on several machines. The scheduler has a generic batch queue, which is set to be load balanced outbound and is directed to several pipe queues on the other machines (and perhaps on itself). These queues are all load balanced inbound. The scheduler machine will direct the available jobs to the various compute resources based on available information which is provided by the relative performance information and the load daemons on the various machines. The relative performance is an indication of the relative power of the machines running the application mix. The load daemons provide information as to the number of NQS jobs running and also the 1, 5 and 15 minute load averages.

The scheduler uses this information to order the possible destinations for the various requests. Given the same number of jobs on two machines, the scheduler will order the destinations with the higher performance machine before the other.

The machines also report completion of jobs to the scheduler. Then the scheduler can act right away to attempt to run the next available job on that machine, thereby minimizing idle cycles.

This configuration is set up by designating one machine to be the scheduler. The rest of the machines (and perhaps the scheduler) act as compute engines. On each of the compute engines create a pipe queue which is load balanced inbound with a single destination being the batch queue where the job will ultimately execute. These execution queues on the compute engines can be set to be pipeonly, so that requests have to be submitted through the scheduler.

On the scheduler, set up a load balanced outbound pipe queue with destinations the pipe queues on the compute engines. The remote machines are configured to have the scheduler be the original system. This means that the scheduler will be notified when jobs complete on the remote systems and will have some indication about the relative load on the various machines.

By default, the compute engines are assumed to be homogeneous, and have the same relative performance. If this approximation is not correct, then you can tell the scheduler the relative performance of each of the machines, using the "set server" command. The relative performance is an integer which can range from 1 to 1024. The larger the number, the greater the performance. The scale is linear, such that a server with a relative performance of 20 is considered twice as powerful as a server with a relative performance of 10. The scheduler will then scale the load of the various compute engines by the relative performance. For example, if two engines have the same number of running jobs, the destinations list for the next job will have the machine with the greater relative performance before the other.

LIMITS
NQS supports many batch request resource limit types that can be applied to an NQS batch queue. The configurability of these limits allows an NQS manager to set batch queue-specific resource limits which all batch requests in the queue must adhere to.

The syntax of a limit in commands of the form SEt Some_limit = ( limit ) queue is quite flexible.

For finite CPU time limits, the acceptable syntax is as follows:

        [[hours :] minutes : ] seconds [.milliseconds]

Whitespace can appear anywhere between the principal tokens, with the exception that no whitespace can appear around the decimal point.

Example time limit-values are:

        1234 : 58 : 21.29    - 1234 hrs 58 mins 21.290 secs
        12345    - 12345 seconds
        121.1    - 121.100 seconds
        59:01    - 59 minutes and 1 second

For all other finite limits (with the exclusion of the nice-value), the acceptable syntax is:

        .fraction [units]

or

        integer [.fraction] [units]

where the integer and fraction tokens represent strings of up to eight decimal digits, denoting the obvious values. In both cases, the units of allocation may also be specified as one of the case insensitive strings:

        b    - bytes
        w    - words
        kb    - kilobytes (2^10 bytes)
        kw    - kilowords (2^10 words)
        mb    - megabytes (2^20 bytes)
        mw    - megawords (2^20 words)
        gb    - gigabytes (2^30 bytes)
        gw    - gigawords (2^30 words)

In the absence of any units specification, the units of bytes are assumed.

For all limit types with the exception of the nice-value, it is possible to state that no limit should be applied. This is done by specifying a limit of "unlimited", or any initial substring thereof.

The complications caused by batch request resource limits first show up when queueing a batch request in a batch queue. This operation is described in the following paragraphs.

If a batch request specifies a limit that cannot be enforced by the underlying UNIX implementation, then the limit is simply ignored, and the batch request will operate as though there were no limit (other than the obvious physical maximums), placed upon that resource type. (See the qlimit(1) command to find out what limits are supported by a given machine.)

For each remaining finite limit that can be supported by the underlying UNIX implementation that is not a CPU time-limit, or UNIX nice-value, the limit-value is internally converted to the units of bytes or words, whichever is more appropriate for the underlying machine architecture.

As an example, a per-process memory size limit value of 321 megabytes would be interpreted as 321 x 2^20 bytes, provided that the underlying machine architecture was capable of directly addressing single bytes. Thus the original limit coefficient of 321 would become 321 x 2^20. On a machine that was only capable of addressing words, the appropriate conversion of 321 x 2^20 bytes / #of-bytes-per-word would be performed.

If the result of such a conversion would cause overflow when the coefficient was represented as a signed-long integer on the supporting hardware, then the coefficient is replaced with the coefficient of: of 2^N-1 where N is equal to the number of bits of precision in a signed long integer. For typical 32-bit machines, this default extreme limit would therefore be 2^31-1 bytes. For word addressable machines in the supercomputer class supporting 64-bit long integers, the default extreme limit would be 2^63-1 words.

Lastly, some implementations of UNIX reserve coefficients of the form: 2^N-1 as synonomous with infinity, meaning no limit is to be applied. For such UNIX implementations, NQS further decrements the default extreme limit so as to not imply infinity.

The identical internal conversion process as described in the preceding paragraphs is also performed for all finite limit-values specified with a particular batch request.

After each applicable request limit has been converted as described above, the resulting limit is then compared against the corresponding limit as configured for the destination batch queue. If the corresponding batch queue limit for all batch request limits is defined as unlimited, or is greater than or equal to the corresponding batch request limit, then the request can be successfully queued, provided that no other anomalous conditions occur. For requests that ask for a limit of infinity, the corresponding queue limit must also be configured as infinity.

These resource limit checks are performed irrespective of the batch request arrival mechanism, either by a direct use of the qsub(1) command, or by the indirect placement of a batch request into a batch queue via a pipe queue. It is impossible for a batch request to be queued in an NQS batch queue if any of these resource limit checks fail.

Finally, if a request fails to specify a limit for a resource limit type that is supported on the execution machine, then the corresponding limit as configured for the destination queue becomes the limit for the request.

Upon the successful queueing of a request in a batch queue, the set of limits under which the request will execute is frozen, and will not be modified by subsequent qmgr(1M) commands that alter the limits of the containing batch queue.

SEE ALSO
passwd(4), plock(2), qdel(1), qdev(1), qlimit(1), qpr(1), qstat(1), and qsub(1)
in the NPSN UNIX User Reference Manual.

NPSN HISTORY
Origin: Sterling Software Incorporated

August 1985 - Brent Kingsbury, Sterling Software
Original release.

May 1986
Second release.

August 1994 - John Roman, Monsanto Company
Release 3.36.