Your system administrator defines the default NQS and NQE database servers and whether your requests will be directed, by default, to NQS or to the NQE database. You can use the default servers and destination, or you can override them.

You can submit requests from your client in the following ways:

How you override a default node or destination depends on how you submit your request. The following sections describe how to submit requests, including how to override these defaults.

---

Note: If you submit a request file as a batch request, after you successfully submit it, you can modify the original file without affecting the request that was submitted.

---

When you submit a request to NQS, and the UNICOS multilevel security (MLS) feature or UNICOS/mk security enhancements are enabled on a remote system, you cannot submit the request to a remote host if that remote host has a workstation access list (WAL) entry for the host of origin that restricts your access to NQS services.

If your NQS requests are on a system that has the UNICOS MLS feature or UNICOS/mk security enhancements enabled, you should execute within your security environment, as defined in the user database (UDB) and the network access list (NAL). See “Using Security Labels When Submitting Requests”, for more information.

Using the NQE GUI to Submit Requests

To submit a request to NQE, access the NQE GUI by entering the nqe command. The initial NQE GUI button bar window will appear (as shown in Figure 1-5). Using the left mouse button, click once on the Submit button.

---

Note: The mouse button settings described in this guide are the default settings.

---

The following Submit window will appear:

Figure 4-1. NQE GUI Submit Window

The Submit window is composed of four sections: the menu bar, the Job to submit: line (the job script file), the job edit area, and the actions button bar.

To submit an existing job script file, do the following:

• Either enter the path name of the request file on the Job to submit: line and press the RETURN key, or select Open from the File menu (the Open option uses a standard Motif file selection interface) and select the request file you want to submit. The request file text appears in the job edit area below the Job to submit line.

  You can modify the content of your request file in the job edit area of the Submit window. To save changes for future use, select Save or Save As on the File menu.

• You can submit a request directly to NQS or to the NQE database. To set the destination for your request, select either the Submit to NQE or Submit to NQS on the General Options menu, and apply the change. If you do not select this option, the value of the NQE_DEST_TYPE environment variable is used, which you can set to be either nqs or nqedb; otherwise, the value of NQE_DEST_TYPE that is set in the /etc/nqeinfo file on your NQS_SERVER is used.

  For additional information about customizing your environment by setting specific environment variables, see Chapter 5, “Customizing Requests”.

  For information about using the NLB and default queue when submitting a request to NQS, see “Using the NLB Default Queue for Submitting Requests”.

  For information about submitting a request to the NQE database, see “Submitting a Request to the NQE Database”.

  For information about using request attributes when submitting a request, see “Using Request Attributes”.

  For information about output options you may want to set before you submit a request, see Chapter 6, “Working with Output Files”.

• If your request will run on a host that uses password validation, use the Actions menu to enter your password.

• To submit the request file, click on the Submit button that is located at the bottom of the Submit window.

  If your request is submitted successfully, you will receive a message similar to one of the following messages:

  • For requests submitted to NQS, you will receive the following message:

    Request number.host submitted to queue:queue.

    
    

  • For requests submitted to the NQE database, you will receive the following message:

    Task id tnumber inserted into database nqedb.

    
    

  For more information about messages received after submitting a request, see “Successful Submissions”, and “Unsuccessful Submissions”. For information about suppressing this message, see “Suppressing Informational Messages”.

To cancel the Submit window, click on the Cancel button that is located at the bottom of the Submit window.

cqsub [file]

qsub [file]

The NLB lets NQE balance the workload of requests across multiple NQS servers. This process is called load balancing. To use load balancing, you must submit requests to the destination-selection queue nqenlb, which is the system default destination-selection queue (but may be configured differently for your site). Usually, an NLB pipe queue named nqenlb exists on each NQS server node.

You can let NQS select a queue for you, or you can specify a queue in which you know you want your request to execute. If you do not specify a queue, NQS initially sends your request to a default queue. The default queue is usually a destination-selection queue. The queue nqenlb is the system default destination-selection queue (but may be configured differently for your site).

When you submit a request to a destination-selection queue, NQS queries the NLB to find the most appropriate batch queue to receive the request, based on site-defined policies. The NLB returns a list of the most appropriate queues. The list is ordered beginning with the most appropriate queue choice.

NQS tries to forward the request to the first queue on the list and continues until the request is accepted or until the list is exhausted.

If your site uses file validation, you must have an .rhosts or .nqshosts file on each system to which a request may be load-balanced. If you receive the No account authorization at transaction peer message, you probably must edit your validation files. For more information on validation, see Chapter 2, “Preparing to Use NQE”.

The following example submits a request to be load-balanced when the default queue is a destination-selection queue:

cqsub jobfile1

The jobfile1 file is submitted to NQS, which queries the NLB and then forwards it to a batch queue.

To determine the name of a destination-selection queue, use the cqstatl -p or qstatl -p command. If nothing is listed in the DESTINATIONS column, the queue is a destination-selection queue.

You might not have a default queue; to specify one, see “Unsuccessful Submissions”.

A request submitted to the NQE database is called a task, and it is assigned a unique task identifier (tid). When you submit a request to the NQE database, the NQE database works with an administrator-defined NQE scheduler to analyze all aspects of your request and determine which NQS server node will receive and process the request.

When the NQE scheduler has chosen a node for your request, the NQE database sends a copy of the request to the batch queue (by default) on the selected NQS server node. The default batch queue is usually named nqebatch. The request is assigned an NQS request identifier (requestid) and is executed.

Because the original request remains in the NQE database, using the NQE database provides a cluster-wide job rerun capability. If the cluster rerun feature is enabled on your NQE cluster, and if a problem occurs during execution and the copy of the request is lost, a new copy can be submitted.

Your system administrator can modify the NQE scheduler to better meet user requirements and system use needs. For example, the scheduler could be modified so that you could indicate a certain amount of CPU units for your request, and the scheduler can interpret units differently by machine types in your group of NQS server nodes in the NQE cluster.

Specifying a Database User Name for Your Request

To submit a request to the NQE database, to control a request that was sent to the NQE database, or to get a status of a request that is in the NQE database, you must have a database user dbuser account (name) with the proper authorization (user privileges). This database user name may be the same as or different from your UNIX or UNICOS login on the client host. Your NQE administrator controls who has access to the database and from which client host.

If the database user name is different from your local client's login name, you must supply the database user name on each of your client requests.

---

Note: To delete, to send a signal to, or to get a status of a request, you must have the same database user name that was used to submit the request to the NQE database.

---

Specify the database user name in the following ways:

• If you use the NQE GUI, select the General Options menu in the Submit window and enter the name in the User Name option field.

• If you use the command line interface, use the -u dbuser= command option of the cqsub command. An example follows:

  cqsub -u dbuser=henry job

  
  

• Set the NQEDB_USER environment variable. An example follows:

  setenv NQEDB_USER henry

  
  

To specify that a request be run under another user's name, see “Using Alternative User Names” in Chapter 5.

When using the Distributed Computing Environment/Distributed File Service (DCE/DFS) to submit requests to NQE, you should note the following:

If you have NQS requests that are on a system that has the UNICOS multilevel security (MLS) feature or UNICOS/mk security enhancements enabled, you must execute requests within your security environment as defined in the user database (UDB) and the network access list (NAL). This security environment remains the same for the duration of the request; that is, you cannot place the setucmp(1) or setulvl(1) command in the NQS request to change the environment. The request's security label is determined by your active security label or is set as specified by using either the cqsub -L or qsub -L command or the cqsub -C or qsub -C command, or by selecting the NQE GUI General Options option on the Configure menu of the Submit window. To specify the active security level of the request, use the -L option; to specify compartments that must be a superset of your active compartments, use the -C option.

This section describes how security labels are determined when you submit NQS requests locally and remotely.

$ setulvl 1
setulvl: New security label is
Level[1:level1] Compartments[none]
$ qsub -L 0 -eo -o nqs.out request.file
Unanticipated transaction failure at local host.

Request attributes are ASCII strings that are to be associated with your request and may be interpreted by the NQE scheduler, the NLB, or NQS.

You may specify zero or more request attributes when submitting a request.

To provide a more efficient or site-specific scheduling, your NQE administrator can configure the NQE database, the NLB, and NQS to interpret the attribute names (and values). This section describes using request attributes.

attribute_name [=value] [,attribute_name [=value]

Using Request Attributes with NQS

You may specify a list of request attributes when you submit a request to NQS. For example, the following submits the request with script jobfile to NQS with the request attributes nastran and big:

cqsub -la "nastran,big" jobfile

If you use the NQE GUI to submit a request, select General Options of the Configure menu in the Submit window. Enter the attributes in the Attribute(s) field and apply your change.

---

Note: Your administrator can configure NQS pipe queues and batch queues to reject or accept requests with certain attributes. This gives greater control over the types of request run at a given time.

---

Using Request Attributes with the NLB

You may specify a list of request attributes when you submit a request to an NLB queue in NQS. For example, the following submits the request with script jobfile to the NLB queue, nqenlb, with the request attributes nastran and big:

cqsub -q nqenlb -la "nastran,big" jobfile

If you use the NQE GUI to submit a request, select General Options of the Configure menu in the Submit window. Enter the attributes in the Attribute(s) field and apply your change.

NQS passes the request attributes to the NLB, which can return a list of destinations based on the attributes as well as system load.

---

Note: If an attribute is not defined in NLB, NQS ignores it. No error message is generated. If the attribute is defined but is not an integer type, NQS generates a log message and the attribute is ignored.

---

Using Request Attributes with the NQE Scheduler

You may specify not only a list of request attributes but also values associated with the attributes when submitting a request to the NQE database. For example, the following offers an attribute called nastran and an attribute called license, which has a value of 2:

cqsub -d nqedb -la "nastran,license=2" jobfile

If you use the NQE GUI to submit a request, select General Options of the Configure menu in the Submit window. Enter the attributes in the Attribute(s) field and apply your change.

The license attribute has the value 2. The attributes are stored in the NQE database with other request information.

The NQE scheduler can use (or ignore) the attributes. If an attribute does not have a value, only the attribute name is stored in the NQE database.

---

Note: Request attributes with explicit values (such as license=2) are completely ignored by both NQS and NLB.

---

After your request has been submitted successfully, you will receive a message; the message you receive will depend on which destination you chose for your request (NQS or NQE database). The following sections describe the message you receive.

Request number.host submitted to queue:queue.

nqs-181 qsub: INFO
  Request number.host: Submitted to queue queue by username(userid).

Request 255.coal submitted to queue: nqenlb.

Task id tnumber inserted into database nqedb.

Task id t4 inserted into database nqedb.

To suppress the informational message when you submit a request, do one of the following:

If your request is not submitted successfully, you receive an error message that describes the problem. The message you receive will depend on which destination you chose for your request (NQS or NQE database). The following sections describe the message you receive.

For more information about solving problems with request submissions, see Chapter 16, “Solving Problems”.

Connect: Connection refused
NETWORK: ERROR: NQE Database connection failure:
        Can't connect to MSQL server on Latte

latte$ cqstatl
NETWORK: ERROR: NQE Database connection failure:
         Connection disallowed.
latte$

Your NQE system administrator can set limits on the NQS system that constrain the maximum number of requests that can be processed concurrently. NQS system limits are important to you because they may affect when (or if) your request will run. For example, if you submit five requests in succession, the last requests probably will not execute immediately because you have exceeded a user run limit.

NQS limits are set on individual queues, queue complexes, and the entire NQS system on a server. A queue complex is a set of local batch queues grouped by the NQE system administrator to simplify NQE administration. Each queue complex can have the same set of limits that a single batch queue can have. global limits restrict the whole NQS system on a host.

Your NQE administrator can set the limits shown in Table 4-1 on individual queues, queue complexes, and on the NQS system as a whole.

To display the current limits, use the commands in Table 4-2:

If you have long jobs that take several hours or more to execute, you can have the system notify you when the request starts and/or completes execution. By default, the mail messages are sent to the user name under which you were logged in when you submitted the request.

---

Note: Mail is sent only by NQS. For requests submitted to the NQE database, any mail requested is sent by the NQS running the copy of the request. If the cluster rerun feature is enabled on your NQE cluster, it is possible that you will receive multiple mail messages if the request is scheduled more than once because the NQE scheduler performs network cluster rerun.

---

To specify that you want to receive mail when your request is routed from a pipe queue, when it begins execution, and when it finishes execution, do one of the following:

If you use these options, mail from NQS would appear as follows in your mail queue (this example is from elm (1)):

N  46 Oct 12 ice_root  (27) NQS request: 59.ice delivered.
N  47 Oct 12 ice_root  (27) NQS request: 59.ice beginning.
N  48 Oct 12 ice_root  (36) NQS request: 59.ice ended.

The mail that informs you that your request has been routed from a pipe queue would be similar to the following:

Subject: NQS request: 59.ice delivered.

Message concerning NQS request: 59.ice delivered.
Request name:   job2
Request owner: jane
Mail sent at:   09:01:55 CDT
Request sent to local queue destination.

Job log follows:

10/12 09:01:53 Arrived in <[email protected]> from <ice>.
10/12 09:01:54 Arrived in <[email protected]> from <[email protected]>.
10/12 09:01:55 Sending <delivered> mail to <jane>.

The mail that informs you that your request has begun execution in a batch queue would be similar to the following:

Subject: NQS request: 59.ice beginning.

Message concerning NQS request: 59.ice beginning.
Request name:   job2
Request owner: jane
Mail sent at:   09:01:55 CDT

Job log follows:

10/12 09:01:53 Arrived in <[email protected]> from <ice>.
10/12 09:01:54 Arrived in <[email protected]> from <[email protected]>.
10/12 09:01:55 Sending <delivered> mail to <jane>.
10/12 09:01:55 Sending <beginning> mail to <jane>.

The job log at the end of the message records that both mail messages were sent.

The mail that informs you that your request has completed execution in a batch queue would be similar to the following:

Subject: NQS request: 59.ice ended.

Message concerning NQS request: 59.ice ended.
Request name:   job2
Request owner: jane
Mail sent at:   09:02:01 CDT
Request exited normally.

_Exit() value was: 0.

Job log follows:

10/12 09:01:53 Arrived in <[email protected]> from <ice>.
10/12 09:01:54 Arrived in <[email protected]> from <[email protected]>.
10/12 09:01:55 Sending <delivered> mail to <jane>.
10/12 09:01:55 Sending <beginning> mail to <jane>.
10/12 09:01:56 Started, pid=<1688>, jid=<1688>, shell=<>, umask=<18>.
10/12 09:01:56 Running in queue <nqebatch>.
10/12 09:01:59 Finished.
10/12 09:01:59 Returning stderr output file.
10/12 09:02:00 Returning stdout output file.
10/12 09:02:01 Sending <ended> mail to <jane>.

If the UNICOS MLS feature or UNICOS/mk security enhancements are enabled on your system, you must have your current active label set appropriately to read mail from NQS. If your request has not yet been initiated, mail is sent to you at the job submission label. If your request has been initiated or has completed execution, mail is sent to you at the job execution label.

To request mail when a request is rerun, do one of the following:

To request that mail be sent to an alternative user name, do one of the following:

If your request does not complete successfully, you receive either an error message in the standard error file or a mail message that describes the problem.

The following example is the mail you will receive from NQS if your validation is not set up correctly:

Message concerning NQS request: 32.latte deleted.
Request name:   STDIN
Request owner: jane
Mail sent at:   17:31:45 CDT
Request could not be routed.

The job you submitted could not be routed to any destination.
Destinations may have been explicitly requested by you, chosen for you
by static pipe queue destinations, or chosen dynamically by the NQE
network load balancer.

The most typical cause for this kind of problem is account validation.
Check that you have a valid account on the target NQS system(s), and
that you have an entry there in your .rhosts and/or .nqshosts files.

See the nqe man page and User Guide for additional information.

System administrators - Check that NQS MID's (mainframe identifiers)
are correctly set up, so that client and server NQS systems know about
each other. Also, try the nlbpolicy command to look at all of the
possible target hosts for an nqs job, given current system load and
NQE policies. And in the nqs logfile, message nqs-527 also shows what
specific destinations were tried.

Request deleted.

  Last destination queue attempted: <[email protected]>

Job log follows:
.
.
.

This message indicates that the problem probably will be a validation file error. The job log at the end of the message, however, may indicate a different error. You should try to interpret it before calling your local support personnel.

Your batch request may have to access a data file on the system. For example, you may want to compile a source program file or process a file of data. When a request begins executing, the current directory is the home directory of the user under whom the request is being executed (just as if that user had logged in interactively).

For example, consider the following request, which is a standard shell script that compiles and then executes a Fortran program called loop.f:

set -x          # Echo commands
ja              # Enable job accounting
date
cd loopdir      # Move to directory where
                # loop.f is stored
f90 -Zu loop.f  # Compile program loop.f
date./a.out         # Execute program a.out
date
rm loop.o a.out # Remove files
echo job complete
ja -csft        # Report job accounting
                # information and disable job
                # accounting

The following two lines are taken from the preceding example. The first line changes the request's current directory to the directory in which loop.f is stored; the second line compiles loop.f.

cd loopdir
f90 -Zu loop.f

Another method of accessing a data file is to embed it in the shell script as a here document. A here document has the following form:

command << 'string'
lines of input
string

The lines of input could be commands or data supplied as standard input to command. The string line defines the end of the lines of input.

The following example shows the compilation of a Fortran program that is created as a here document, and then the subsequent executing of the program by using data that also comes from a here document:

cat > test.f << 'DELIMIT'
      PROGRAM ADD
C   Read data file to get number of data points to read
C   into an array; add them up and write out the sum
     DIMENSION A(100)
     REAL A, SUM
     INTEGER N
     OPEN (5, FILE= 'DATA')
     READ (5,1) N
1    FORMAT(I3)
     DO 10, I=1,N
     READ (5,2) A(I)
2    FORMAT (F 10.5)
10   CONTINUE
     SUM=0.0
     DO 20, I=1,N
     SUM=SUM + A(I)
20   CONTINUE
     WRITE(6,3) N, SUM
3    FORMAT (' sum of the ',I3,' numbers is ', G15.5)
      END
DELIMIT
cat > DATA << '*EOF*'
  5
      10.0
      20.0
      30.0
      40.0
      50.0
f90 test.f./a.out

In the next example, the prog program is executed twice, using two different sets of data:

prog << 'EOT'
2.2 8.9
EOT
prog << 'EOT'
8.6 123.4
EOT

If you are running UNICOS or UNICOS/mk, and your system or user profile does not automatically enable job accounting, you can include ja(1) commands within your batch request. The ja command provides information about the resources used when your request executes. The ja command can take several options and arguments, such as the name of a file to contain the report (the default is $TMPDIR/.jacctxxxx; xxxx is the UNICOS or UNICOS/mk job identifier). For a full description of the ja command, see the ja(1) man page.

In the following example script, the first ja command simply turns on job accounting, writing the information to the default file. The second ja command (with the -s option) writes a report to the standard output file when the script file is executed. When the request completes execution, the contents of the temporary directory $TMPDIR (including the .jacctxxxx file) are deleted automatically.

ja
sleep 45
date
pwd
ls
ja -s

To view the job accounting report, you can examine the standard output file produced by the execution of the request. For more information about a request's output files, see Chapter 6, “Working with Output Files”. The following output file shows the report produced by running the preceding script. (If the request ran under the C shell, a message written to the start of the output file indicates that the normal C shell job control facilities were not available for this job because it was run in batch mode, rather than from a terminal (tty).)

Thu Feb 19 16:09:50 CST 1998
/u/snow
testjob
testjob.e11562
testjob.o11562
tutorial


Job Accounting - Summary Report
===============================

Job Accounting File Name         : /tmp/jtmp.004076a/.jacct1093
Operating System                 : sn1234 xyz 9.2.1bm abc.1 CRAY C90
User Name (ID)                   : snow (10334)
Group Name (ID)                  : crazy (100)
Account Name (ID)                : snow (10334)
Job ID                           : 1093
Report Starts                    : 02/19/98 16:09:04
Report Ends                      : 02/19/98 16:09:50
Elapsed Time                     :           46      Seconds
User CPU Time                    :            0.2327 Seconds
System CPU Time                  :            0.0791 Seconds
I/O Wait Time (Locked)           :            0.0391 Seconds
I/O Wait Time (Unlocked)         :            0.1485 Seconds
CPU Time Memory Integral         :            0.0223 Mword-seconds
SDS Time Memory Integral         :            0.0000 Mword-seconds
I/O Wait Time Memory Integral    :            0.0027 Mword-seconds
Data Transferred                 :            0.1786 MWords
Maximum memory used              :            0.2051 MWords
Logical I/O Requests             :           87
Physical I/O Requests            :          108
Number of Commands               :            6
Billing Units                    :            0.4781
logout

If you are running UNICOS or UNICOS/mk, you may receive an NQS error message while you are using NQS. The NQS user error messages have a group code of nqs. To display the explanation of a message, use the explain(1) command. For more information, see the explain(1) man page. The following example shows NQS error messages and the use of the explain(1) command:

% qmsg -j -f msg_in 10
nqs-272 qmsg: WARNING
  Error opening file <abc/u0/snow/msg_in>, errno = <13>.
nqs-20 qmsg: WARNING
  Errno <13> = <Permission denied>.
% explain nqs272
Error opening file <file>, errno = <errno>.

NQS tried to use the open(2) system function to open file <file>,
but failed. The reason for the failure is identified by <errno>.
% explain nqs20
Errno <errno> = <error_desc>.

The specified error <errno> has an associated description of <error_desc>.

---

Note:: This functionality is available only on UNICOS, UNICOS/mk, and IRIX systems.

---

If the operating system is shut down or crashes before the request completes execution, you do not necessarily have to resubmit a batch request because NQS has job recovery capabilities. NQS uses the operating system checkpoint facilities, as follows:

The following two sections describe how you can ensure that your requests take advantage of these recovery facilities, or how to ensure that your request does not use the facilities.

qchkpnt

ja                   # Enable job accounting
date
cd loopdir           # Move to directory where
                     # loop.f is stored
f90 -Zu loop.f       # Compile program loop.f
qchkpnt
date./a.out              # Execute program a.out
date
rm loop.o a.out      # Remove files
echo job complete
ja -csft             # Report job accounting
                     # information and disable
                     # job accounting

Request <1.subzero>: Request received SIGRPE or SIGUME signal; request requeued.

Request <1.subzero>: Request received SIGPEFAILURE signal; request requeued.

A temporary directory is available to batch requests for the duration of their execution. Each batch request has its own unique temporary directory. When the batch request completes execution, or aborts with an error, NQS deletes the directory, along with any files contained in the directory.

Typically, temporary directories are created within the /tmp directory, although this depends on your site configuration. The name takes the form nqs.xxxxx (xxxxx is any unique string). The name of the directory is available to a batch request in the TMPDIR environment variable.

You can use the temporary directory to hold intermediate files generated by your request that are not required when the request ends.

In the following example script file, the source program and executable file created by the cc compilation line are written to $TMPDIR. After the request completes execution, these files are deleted automatically, along with the temporary directory.

cd $TMPDIR
pwd
cat <<EOF > test.c
main () {
.
program
.
}
EOF
cc -o test test.c
ls -la
./test