Chapter 8

API Library

8.1 LIBRARY FUNCTIONS

This chapter describes the API library functions used to create application programs with NQS.

intro(3NQS-N)		overview explanation of the NQS library
NQSgetquename(3NQS-N)		getNQS queue name information list
NQSgetbqueattrb(3NQS-N)		get NQS batch queue information list
NQSgetreqid, NQSgetreqidbyqueue, NQSgetreqidbyuser(3NQS-N)		get NQS request ID information list
NQSgetbreqattrb(3NQS-N)		get NQS batch request information list
NQSinfolstnext, NQSinfolstprev, NQSinfolstnum, NQSinfolstcurr, NQSinfolstfree(3NQS-N)		operate NQS information list
NQSinfoelmntqname(3NQS-N)		see NQS queue name information list
NQSinfoelmntrimid, NQSinfoelmntriseqno(3NQS-N)		see NQS request ID information list
NQSinfoelmntatrfmt, NQSinfoelmntatrgrp, NQSinfoelmntatrtype, NQSinfoelmntatrsize, NQSinfoelmntatrintval, NQSinfoelmntatrstrval, NQSinfoelmntatrlimit(3NQS-N)		see NQS batch queue and request information list
NQSreqidtostr, NQSreqidtonum, NQSmachname, NQSmachid(3NQS-N)		translate NQS request ID
NQSgetbyteperword(3NQS-N)		get number of bytes per word
NQSqwatch(3NQS-N)		NQS event notification
nqsstat(4NQS-N)		NQS data structure used by API libraries

8.2 LIBRARY FUNCTION FORMAT

NAME

This section provides the library function name and a brief description of the library function.

SYNOPSIS

This section shows the required library function syntax, including arguments.

DESCRIPTION

This section describes the library function syntax, how the functions work, and other detailed information.

NOTES

This section provides generally helpful hints about the use of the utility.

EXAMPLES

This section provides examples of library function usage.

SEE ALSO

This section provides the reference name including the related information.

NAME

intro - overview explanation of the NQS library

DESCRIPTION

The NQS library provides functions enabling the use of NQS functions in C. To link the NQS library, specify -L/usr/lib/nqs -lnqsapi in the cc command line.

Area Allocation

The NQS library function allocates a dynamic area used to store execution results. Since this area is allocated in the library using the malloc function, release it by using the NQSfree function after performing data reference. The address returned by the library function is not always the first address of the malloc area. Therefore, the area cannot be directly released by using the free function.

Block Structure

The result area is divided into multiple variable-length blocks. Each block contains result data or is divided into lower-level blocks. The address of the uppermost first block is returned by the library function.

Several macros are provided to access the result area.

• NQSblocknext(p)
  Returns the address of the block specified, indicated by pointer p. Returns NULL when there is no subsequent block.

• NQSblockchild(p)
  Returns the address of the first block of the lower blocks indicated by pointer p. Returns NULL when there are no lower blocks.

• NQSblockdata(p)
  Returns the contents of the block indicated by pointer p.

• NQSblocksize(p)
  Returns the size of the block indicated by pointer p.

• NQSblockcode(p)
  Returns the reference code number and data type of the block indicated by pointer p. The reference code number is determined when the return value of this function is AND-gated with macro constant NQSAPI_CODE. See the block data format for data type.

Example



Figure 8-1 Block Structure

For example, in the preceding figure specify the following to access data A.

p = Return value of the library function;
p = NQSblocknext(p);
p = NQSblockchild(p);
p = NQSblocknext(p);
p = NQSblocknext(p);
A_ptr = (type_of_A *) NQSblockdata(p);

Block Data Format

Each block has individual data types. The following data types are supported.

• Block set type
  The contents of the block are divided into multiple lower blocks. The NQSblockcode() value is AND-gated with macro constant NQSAPI_COMP to produce nonreturn-to-zero.

• Character string type
  The character string is terminated with 0. The NQSblockcode() value is AND-gated with macro constant NQSAPI_STRING to produce nonreturn-to-zero.

• long integer array type
  The block is a long integer array. It may provide the reference structure used to access the contents of the block. The NQSblockcode() value is AND-gated with macro constant NQSAPI_INT4 to produce nonreturn-to-zero.

Reference Code

A reference code indicating the data contents is appended to each block. When the block sequence is unclear, use this reference code to search for the block.

Common Blocks

Each library function returns the result area with an individual format. Only the first two blocks return the definition of the data contents.

• Command status
  This block contains a function error code, etc.
  • Refere nce code 1
  • long array type
  • Reference structure

  
  	struct NQSapistat {
  
  	long status;
  		long tcmcode;
  		long total_size;
  
  		long version;
  		long reserve[4];
  
  	}
  

  status

  the termination state of the function. The meanings of the values are as follows:

  0

  Normal termination.

  1

  The function failed due to incorrect timing or some other reason, but it may be terminated normally if reexecuted.

  2

  When the limit set by the administrator is exceeded or when the user does not have the necessary privilege to use the system.

  3

  Invalid specification by the user, such as an option specification error.

  4

  Invalid setting by the administrator, such as an environment setting error.

  5

  Internal errors caused by NQS itself.

  100

  Normal termination and abnormal termination are mixed.

  tcmcode

  the reserved area.

  total_size

  the size of the overall result area.

  version

  the version of the NQS library.

  reserve

  the spare area.

• Message
  The message indicates the contents of an error.
  • Reference code 2
  • Character string type

NAME

NQSgetquename - get NQS queue name information

SYNOPSIS

#include <nqsstat.h>


int NQSgetquename(data, type)
struct nqsinfoindex **data;
int type;

DESCRIPTION

NQSgetquename gets a NQS information list of name of queues which is in the specified type. The following are the options for type.

001

batch queues

002

device queues

004

network queues

010

pipe queues

This function automatically allocates memory for the list. To set the memory free, please use NQSinfolstfree(3NQS).

The return value is as follows.

0

The information is successfully retrieved.

1

The memory allocation failed.

2

Specified type is invalid.

You should use NQSinfolst*(3NQS) functions to operate the retrieved NQS information list, and NQSinfoelmntqname(3NQS) to see the data in the list.

SEE ALSO

NQSinfolstnext(3NQS), NQSinfolstprev(3NQS), NQSinfolstnum(3NQS),
NQSinfolstcurr(3NQS), NQSinfolstfree(3NQS), NQSinfoelmntqname(3NQS)

NQSstat(4NQS)

NAME

NQSgetbqueattrb - get NQS batch queue information

SYNOPSIS

#include <nqsstat.h>


int NQSgetbqueattrb(queuename, data, group1, group3, group4, group5)
char *queuename;
struct nqsinfoindex **data;
int group1;
int group3;
int group4;
int group5;

DESCRIPTION

NQSgetbqueattrb gets a NQS information list of batch queue specified as queuename.

This function automatically allocates memory for the list. To set the memory free, please use NQSinfolstfree(3NQS).

As group1, group3, group4, and group5, specify the data type of each data group by on or off of the flag bit. For the data type flag of each data groups, see NQSstat(4NQS)).

The return value is as follows.

0

The information is successfully retrieved.

1

The memory allocation failed.

2

The specified arguments are invalid.

3

The specified queue does not exist.

You should use NQSinfolst*(3NQS) functions to operate the retrieved NQS information list, and NQSinfoelmntatr*(3NQS) functions to see the data in the list.

EXAMPLES

The following example shows the queue priority, per-request CPU time limit, and nice value of a queue "bq1".

#include <stdio.h>
#include <nqsstat.h>
main()
{
        struct nqsinfoindex *index;
        int idata;
        short posi=1;
        int ret;
        struct nqsreslim limitdata;
        int group1=0, group3=0, group4=0, group5 = 0;
        group1 |= NQSIT1_QPRIORITY;
        group4 |= NQSIT4_CPUTIME;
        group5 |= NQSIT5_NICE;
        if(ret = NQSgetbqueattrb("bq1",&index, group1, group3, group4, group5)){
                printf("error%d\n",ret);
                exit(1);
        }
        while (posi){
                switch(NQSinfoelmntatrfmt(index)){
                case NQSIDF_INT:
                        NQSinfoelmntatrintval(index,&idata);
                        switch(NQSinfoelmntatrgrp(index)){
                        case NQSIG_BQUEATTR:
                                if(NQSinfoelmntatrtype(index)== NQSIT1_QPRIORITY);
                                printf("Qpriority: %d\n", idata);
                                break;
                        case NQSIG_SCDPRMT:
                                if(NQSinfoelmntatrtype(index)== NQSIT5_NICE);
                                printf("Nice: %d\n", idata);
                                break;
                        }
                        break;
                case NQSIDF_RESLIMIT:
                        NQSinfoelmntatrlimit(index,&limitdata);
                        switch(NQSinfoelmntatrgrp(index)){
                        case NQSIG_PRRESLIM:
                            if(NQSinfoelmntatrtype(index)==NQSIT4_CPUTIME){
                                printf("Per Request CPU time limit:");
                                if (limitdata.flags & LMF_INFINI){
                                       printf("Unlimited\n");
                                }else{
                                       printf("MAX=");
                                       printf("%d",limitdata.max_quota);
                                       printf(".%d ",limitdata.max_attribute);
                                       printf("WARN=");
                                       printf("%d",limitdata.warn_quota);
                                       printf(".%d ",limitdata.warn_attribute);
                                       printf("\n");
                                }
                            }
                            break;
                        }
                        break;
                }
                posi = NQSinfolstnext(index);
        }
        NQSinfolstfree(index);
}

SEE ALSO

NQSinfolstnext(3NQS), NQSinfolstprev(3NQS), NQSinfolstnum(3NQS),
NQSinfolstcurr(3NQS), NQSinfolstfree(3NQS), NQSinfoelmntatrfmt(3NQS),
NQSinfoelmntatrgrp(3NQS), NQSinfoelmntatrtype(3NQS), NQSinfoelmntatrsize(3NQS),
NQSinfoelmntatrintval(3NQS), NQSinfoelmntatrstrval(3NQS), NQSinfoelmntatrlimit(3NQS)

NQSstat(4NQS)

NAME

NQSgetreqid, NQSgetreqidbyqueue, NQSgetreqidbyuser - get NQS request ID information

SYNOPSIS

int NQSgetreqid(data, status)
struct nqsinfoindex **data;
int status;

int NQSgetreqidbyqueue(data, status, queuename)
struct nqsinfoindex **data;
int status;
char *queuename;

int NQSgetreqidbyuser(data, status, uid)
struct nqsinfoindex **data;
int status;
int uid;

DESCRIPTION

NQSgetreqid gets the NQS information list of the request ID of requests by specifying the status attribute.

This function automatically allocates memory for the list. To set the memory free, please use NQSinfolstfree(3NQS).

The return value is as follows.

0

The information is successfully retrieved.

1

The memory allocation failed.

2

The specified status is invalid.

NQSgetreqidbyqueue gets NQS information list of the request ID of requests which are submitted into the queue by specifying the queuename and status attributes.

This function automatically allocates memory for the list. To set the memory free, please use NQSinfolstfree(3NQS).

The return value is as follows.

0

The information is successfully retrieved.

1

The memory allocation failed.

2

The specified status is invalid.

3

The specified queue does not exist.

NQSgetreqidbyuser gets NQS information list of the request ID of requests which are owned by the user specified in the uid and status attributes.

This function automatically allocates memory for the list. To set the memory free, please use NQSinfolstfree(3NQS).

The return value is as follows.

0

The information is successfully retrieved.

1

The memory allocation failed.

2

The specified status is invalid.

3

The specified user ID is invalid.

As the status, SREQ_* in NQSstat(4NQS) can be specified.

You should use NQSinfolst*(3NQS) functions to operate the retrieved NQS information list, and NQSinfoelmntrimid(3NQS) or NQSinfoelmntriseqno(3NQS) to see the data in the list.

SEE ALSO

NQSinfolstnext(3NQS), NQSinfolstprev(3NQS), NQSinfolstnum(3NQS),
NQSinfolstcurr(3NQS), NQSinfolstfree(3NQS), NQSinfoelmntrimid(3NQS),
NQSinfoelmntriseqno(3NQS)

NQSstat(4NQS)

NAME

NQSgetbreqattrb - get NQS batch request information

SYNOPSIS

#include <nqsstat.h>


int NQSgetbreqattrb(seqno, mid, data, group2, group3, group4, group5)
int seqno;
mid_t mid;
struct nqsinfoindex **data;
int group2;
int group3;
int group4;
int group5;

DESCRIPTION

NQSgetbreqattrb gets a NQS information list of batch request specified as seqno and mid.

This function automatically allocates memory for the list. To set the memory free, please use NQSinfolstfree(3NQS).

As group2, group3, group4, and group5, specify the data type of each data group by on or off of the flag bit. For the data type flag of each data groups, see NQSstat(4NQS).

The return value is as follows.

0

The information is successfully retrieved.

1

The memory allocation failed.

2

The specified arguments are invalid.

3

The specified queue does not exist.

You should use NQSinfolst*(3NQS) functions to operate the retrieved NQS information list, and NQSinfoelmntatr*(3NQS) functions to see the data in the list.

EXAMPLES

The following example shows the request priority, per-request CPU time limit, and nice value of a batch request which has 15 as the sequence number, and 136 as the machine ID.

#include <stdio.h>
#include <nqsstat.h>
main()
{
        struct nqsinfoindex *index;
        int idata;
        short posi=1;
        int ret;
        struct nqsreslim limitdata;
        int group1=0, group3=0, group4=0, group5 = 0;
        group1 |= NQSIT2_RPRIORITY;
        group4 |= NQSIT4_CPUTIME;
        group5 |= NQSIT5_NICE;
        if(ret = NQSgetbreqattrb(15,136, &index, group1, group3, group4, group5)){
                printf("error%d\n",ret);
                exit(1);
        }
        while (posi){
                switch(NQSinfoelmntatrfmt(index)){
                case NQSIDF_INT:
        }
        while (posi){
                switch(NQSinfoelmntatrfmt(index)){
                case NQSIDF_INT:
                        NQSinfoelmntatrintval(index,&idata);
                        switch(NQSinfoelmntatrgrp(index)){
                        case NQSIG_BREQATTR:
                                if(NQSinfoelmntatrtype(index)== NQSIT2_RPRIORITY);
                                printf("Rpriority: %d\n", idata);
                                break;
                        case NQSIG_SCDPRMT:
                                if(NQSinfoelmntatrtype(index)== NQSIT5_NICE);
                                printf("Nice: %d\n", idata);
                                break;
                        }
                        break;
                case NQSIDF_RESLIMIT:
                        NQSinfoelmntatrlimit(index,&limitdata);
                        switch(NQSinfoelmntatrgrp(index)){
                        case NQSIG_PRRESLIM:
                            if(NQSinfoelmntatrtype(index)== NQSIT4_CPUTIME){
                                printf("Per Request CPU time limit:");
                                if (limitdata.flags & LMF_INFINI){
                                        printf("Unlimited\n");
                                }else{
                                    printf("MAX=");
                                    printf("%d",limitdata.max_quota);
                                    printf(".%d ",limitdata.max_attribute);
                                    printf("WARN=");
                                    printf("%d",limitdata.warn_quota);
                                    printf(".%d ",limitdata.warn_attribute);
                                    printf("\n");
                                }
                            }
                            break;
                        }
                        break;
                }
                posi = NQSinfolstnext(index);
        }
        NQSinfolstfree(index);
}

SEE ALSO

NQSinfolstnext(3NQS), NQSinfolstprev(3NQS), NQSinfolstnum(3NQS),
NQSinfolstcurr(3NQS), NQSinfolstfree(3NQS), NQSinfoelmntatrfmt(3NQS),
NQSinfoelmntatrgrp(3NQS), NQSinfoelmntatrtype(3NQS), NQSinfoelmntatrsize(3NQS),
NQSinfoelmntatrintval(3NQS), NQSinfoelmntatrstrval(3NQS), NQSinfoelmntatrlimit(3NQS)

NQSstat(4NQS)

NAME

NQSinfolstnext, NQSinfolstprev, NQSinfolstnum, NQSinfolstcurr, NQSinfolstfree - operate NQS information list

SYNOPSIS

#include <nqsstat.h>


int NQSinfolstnext(head)
struct nqsinfoindex *head;

int NQSinfolstprev(head)
struct nqsinfoindex *head;

short NQSinfolstnum(head)
struct nqsinfoindex *head;

short NQSinfolstcurr(head)
struct nqsinfoindex *head;

void NQSinfolstfree(head)
struct nqsinfoindex *head;

DESCRIPTION

NQSinfolst * functions operate a NQS information list of NQS queues and requests. You should use these functions for the list gotten by NQSget*(3NQS) functions. If you use other functions, you may be unable to see the date in the list, or to set the allocated memory free.

NQSinfolstnext moves a pointer of the information list forward, and returns the number of the member indicated by the pointer. If the pointer could not move, 0 is returned.

NQSinfolstprev moves a pointer of the information list back, and returns the number of the member indicated by the pointer. If the pointer could not move, 0 is returned.

NQSinfolstnum returns how many members are included in the list.

NQSinfolstcurr returns the number of the member indicated by the pointer.

NQSinfolstfree sets the memory allocated to get NQS information list free.

SEE ALSO

NQSgetquename(3NQS), NQSgetbqueattrb(3NQS), NQSgetreqid(3NQS),
NQSgetreqidbyuser(3NQS), NQSgetreqidbyqueue(3NQS), NQSgetbreqattrb(3NQS)

NQSstat(4NQS)

NAME

NQSinfoelmntqname - see the NQS queue name information list

SYNOPSIS

#include <nqsstat.h>


int NQSinfoelmntqname(head, strval)
struct nqsinfoindex *head;
char *strval;

DESCRIPTION

NQSinfoelmntqname sees the NQS queue name information list gotten by NQSgetquename(3NQS), and sets the queue name currently pointed to the argument strval.

You should use this function to see the list gotten by NQSgetquename(3NQS). If the other functions are used, you may be unable to see data or to set the memory free.

The return value is as follows.

0

The information is successfully retrieved.

1

Unable to see the data in the list.

SEE ALSO

NQSgetquename(3NQS),

NQSstat(4NQS)

NAME

NQSinfoelmntrimid, NQSinfoelmntriseqno - see the NQS request ID information list

SYNOPSIS

#include <nqsstat.h>


int NQSinfoelmntrimid(head, intval)
struct nqsinfoindex *head;
mid_t *intval;

int NQSinfoelmntriseqno(head, intval)
struct nqsinfoindex *head;
int *intval;

DESCRIPTION

NQSinfoelmntrimid sees the NQS request ID information list gotten by NQSgetreqid*(3NQS) functions, and sets the machine id of currently pointed request to the argument intval.

NQSinfoelmntriseqno sees the NQS request ID information list gotten by NQSgetreqid*(3NQS) functions, and sets the sequence number of currently pointed request to the argument intval.

You should use these functions to see the list gotten by NQSgetreqid*(3NQS) functions. If the other functions are used, you may be unable to see data or to set the memory free.

The return value is as follows.

0

The information is successfully retrieved.

1

Unable to see the data in the list.

SEE ALSO

NQSgetreqid(3NQS), NQSgetreqidbyuser(3NQS), NQSgetreqidbyqueue(3NQS)

NQSstat(4NQS)

NAME

NQSinfoelmntatrfmt, NQSinfoelmntatrgrp, NQSinfoelmntatrtype, NQSinfoelmntatrsize, NQSinfoelmntatrintval, NQSinfoelmntatrstrval, NQSinfoelmntatrlimit - see the NQS information list of batch queue or request

SYNOPSIS

#include <nqsstat.h>


int NQSinfoelmntatrfmt(head)
struct nqsinfoindex *head;

int NQSinfoelmntatrgrp(head)
struct nqsinfoindex *head;

int NQSinfoelmntatrtype(head)
struct nqsinfoindex *head;

int NQSinfoelmntatrsize(head)
struct nqsinfoindex *head;

int NQSinfoelmntatrintval(head, intval)
struct nqsinfoindex *head;
int *intval;

int NQSinfoelmntatrstrval(head, strval)
struct nqsinfoindex *head;
char *strval;

int NQSinfoelmntatrlimit(head, limit)
struct nqsinfoindex *head;
struct nqsreslim *limit;

DESCRIPTION

NQSinfoelmntatr* functions see the NQS queue information list gotten by NQSgetbqueattrb(3NQS), and NQS request information list gotten by NQSgetbreqattrb(3NQS).

You should use this function to see the list gotten by NQSgetbqueattrb(3NQS) or NQSgetbreqattrb(3NQS). If the other functions are used, you may be unable to see data or to set the memory free.

NQSinfoelmntatrfmt returns the data format of the currently pointed data in the NQS information list. For the data format, see NQSstat(4NQS).

NQSinfoelmntatrgrp returns the data group ID of the currently pointed data in the NQS information list. For the group ID, see NQSstat(4NQS).

NQSinfoelmntatrtype returns the data type ID of the currently pointed data in the NQS information list. For the type ID, see NQSstat(4NQS).

NQSinfoelmntatrsize returns the data size of the currently pointed data in the NQS information list.

NQSinfoelmntatrintval sets the int type data of the currently pointed in the NQS information list to the intval. When you use this function, please check the data format by NQSinfoelmntatrfmt first. The return value is as follows.

0

The information is successfully retrieved.

1

The data format is invalid.

NQSinfoelmntatrstrval sets the string type data of the currently pointed in the NQS information list to the strval. When you use this function, please check the data format by NQSinfoelmntatrfmt first. The return value is as follows.

0

The information is successfully retrieved.

1

The data format is invalid.

NQSinfoelmntatrlimit sets the resource limit struct type data of the currently pointed in the NQS information list to the limit. When you use this function, please check the data format by NQSinfoelmntatrfmt first. The return value is as follows.

0

The information is successfully retrieved.

1

The data format is invalid.

SEE ALSO

NQSgetbqueattrb(3NQS), NQSgetbreqattrb(3NQS)

NQSstat(4NQS)

NAME

NQSreqidtostr, NQSreqidtonum, NQSmachname, NQSmachid - translate request ID

SYNOPSIS

#include <nqsstat.h>


int NQSreqidtostr(strings, seqno, mid)
char *strings;
int seqno;
mid_t mid;

int NQSreqidtonum(seqno, mid, strings)
int *seqno;
mid_t *mid;
char *strings;

int NQSmachname(strings, mid)
char *strings;
mid_t mid;

int NQSmachid(mid, strings)
mid_t *mid;
char *strings;

DESCRIPTION

NQSreqidtostr translates from sequence number and machine ID specified as seqno and mid to a request ID (a character strings shown as "sequence-number.machine-name), and set it to strings. The return value is as follows.

0

The translation succeeded.

less than 0

The translation failed.

NQSreqidtonum translates from the request ID specified as strings to a sequence number and a machine ID, and set it to seqno and mid. The return value is as follows.

0

The translation succeeded.

less than 0

The translation failed.

NQSmachname translates from machine ID specified as mid to a machine name, and set it to strings. The return value is as follows.

0

The translation succeeded.

less than 0

The translation failed.

NQSmachnid translates from machine name specified as strings to a machine ID, and set it to mid. The return value is as follows.

0

The translation succeeded.

less than 0

The translation failed.

NAME

NQSgetbyteperword - get number of bytes per word

SYNOPSIS

int NQSgetbyteperword();

DESCRIPTION

NQSgetbyteperword returns the number of bytes per word treated by NQS.

The return value is as follows.

positive number

number of bytes(normal termination)

negative number

abnormal termination

NAME

NQSqwatch - NQS event notification

SYNOPSIS

struct NQSblockhead *NQSqwatch(argument)
char *argument

DESCRIPTION

NQSqwatch notifies upper programs of realtime request operations and queue status changes in NQS. It receives events from the NQSdaemon using FIFO. The procedure is as follows.
1. Declare the start of the use of the NQSqwatch function to obtain the FIFO path name (-s option).

2. Register the events to be posted in FIFO (-e option).

3. Wait for an event (-r option).

4. Release event registration (-c option).

5. Declare termination of the use of the NQSqwatch function (-x option).

See intro(3NQS) for the format method and use of the result area returned as the function value.

Specify a character string for the argument consisting of one of the option character strings listed in the following explanation section.

Options:

-s

Starts the use of the event monitor function.

The third block in the result area contains a character string. This character string indicates the path name of the FIFO for event notification. Specify this option when the subsequent NQSqwatch functions are used.

-x fifoname

Terminates the use of the event monitor function.

Specify the path name obtained by specifying -s option as the argument of NQSqwatch in fifoname.

-e [-f] fifoname eventtype detail [target...]

Registers the events to be posted in FIFO.

Specify the path name obtained by specifying -s option as the argument of NQSqwatch in fifoname.

Specify the event condition in the eventtype and subsequent fields. For a more detailed explanation, see the description of event conditions.

When -f is specified simultaneously, registration is released for only one received event.

The third block in the result area contains a character string. This character string indicates the event registration ID, which is used when releasing event registration and the identification of received events.

-c fifoname entryid

Releases the event registration.

Specify the path name obtained by specifying the -s option as the argument of NQSqwatch in fifoname.

Specify the registration ID obtained by specifying the -e option as the argument of NQSqwatch in entryid.

-r [-n] [-z] [-t timeout] fifoname

Waits for an event and returns the contents of the event to the result area.

Specify the path name obtained by specifying the -s option as the argument of NQSqwatch in fifoname.

When -n is specified simultaneously, the option does not wait until an event occurs, instead the command terminates immediately.

When -z is specified simultaneously, the option erases all events that occurred before the specification.

When -t is specified simultaneously, the option times out after the specified time elapses. Specify a time in seconds for timeout.

The third and subsequent blocks in the result area contain the contents of events. See the explanation of the event format.

Event Conditions:

Event conditions are described according to the major classification, minor classification, and matching conditions.

• Major classification
  Specify numerical values.

• Minor classification
  Specify codes. The meanings of codes vary with the major classification. Multiple codes, described in succession, enable the system to await multiple events simultaneously.

• Matching conditions
  Specify the matching conditions using the option and argument format. The conditions that can be specified vary with the major classification.
  • Request related events
    These events occur when the status of a request changes. Specify a value of 1 for the major classification. Minor classification codes are as follows.

    A

    generation of a request

    B

    termination of a request

    C

    moving a request in

    D

    moving a request out

    E

    local moving in of a request

    F

    local moving out of a request

    G

    status change of a request (QUEUE, HOLD, WAIT, RUN, SUS)

    I

    parameter change of a request

    M

    execution start of a request

    N

    execution completion of a request

    U

    restart file creation of a request

    V

    restart file deletion of a request

    W

    starting restart of a request checkpointed by users

    When a request is transferred to a remote machine, only B, C, and G can be monitored by the request submitting source. Others can be monitored only on the machine where the request exists.

    The matching conditions are as follows.

    -q queue - queue name
    -i reqid - request ID
    -h hostname - host name

  • Queue operation related events
    Events occurring with the queue operation. Specify a value of 10 for the major classification. The following minor classification codes are supported.

    A

    start

    B

    stop

    C

    enable

    D

    disable

    E

    creation

    F

    deletion

    G

    modification of destinations

    H

    modification of access limit

    I

    modification of parameters

    Matching conditions are as follows:

    -q queue - queue name
    -h hostname - host name

  • NQS operation related events
    Events occurring in NQS operation. Specify a value of 100 for the major classification. The following minor classification codes are supported.

    A

    starting of NQS

    B

    shutdown of NQS

    C

    timeout of communication among NQS

    D

    starting of NQS client

    E

    ending of NQS client

    F

    starting of NQS server

    G

    ending of NQS server

    H

    accepting to find NQS servers

  • Specification examples
    To await the termination or other status change of the request:

    
    	1 BG -i 100.host1
    

    To change the number of requests in the queue:

    
    	1 ABCDEF -q batch1
    

Event Format:

The third and subsequent blocks contain the following data. Data contained in the ninth and subsequent blocks varies with the event type.

• Common
  

  3

  spare area.

  4

  event registration ID (character string).

  5

  event occurrence time (time_t type x 1).

  6

  event major classification (character string). See the explanation of the event conditions.

  7

  event minor classification (character string). See the explanation of the event conditions.

  8

  machine name (character string).

• Request related events
  

  9

  request ID (character string).

  10

  queue name (character string).

  11

  request status (integer x 1).

  0000002	Running
  0000010	Queued
  0000020	Waiting
  0000040	Holding
  0000100	Arriving
  0010000	Exited
  0020000	Routed (the correct status is unknown)
  0100002	Suspending
  0200002	Routing

  12

  termination state of the request (integer array).

  
  	struct NQSreqexitstate {
  		long reason;
  		long exitcode;
  		mid_t execmid;
  		time_t starttime;
  		time_t endtime;
  		long reserve[3];
  	}
  

  reason

  the reason for the termination of the request. This corresponds to the termination code of the qwait command.

  exitcode

  the termination code or signal number of the request.

  execmid

  the machine ID of the machine that executes the request.

  starttime

  spare area.

  endtime

  the termination time of the request execution.

  reserve

  spare area.

  13

  number of requests in the queue (integer array).

  
  	struct NQSreqnum {
  		long total;
  		long queued;
  		long run;
  		long wait;
  		long hold;
  		long arrive;
  		long reserve[10];
  	}
  

  total	total number of requests
  queued	number of queued requests
  run	number of running requests
  wait	number of waiting requests
  hold	number of held requests
  arrive	number of arriving requests
  reserve	spare area

  14

  number of requests on the machine (integer array). See the above explanation of the number of requests in the queue for more information about the contents of the integer array.

• Queue operation related events
  

  9

  queue name (character string).

  10

  queue status (integer).

  000001

  Started

  000002

  Enabled

  000010

  Precheck function is set

  000020

  Stay wait is set

  002000

  Transpipe attribute is set

  004000

  Load balance attribute is set

  020000

  Access is restricted

  040000

  Pipeonly attribute is set

Polling:

An event occurring inside the NQS system is posted, through FIFO, with the path name returned by specifying the -s option as the argument of NQSqwatch. Opening the event in asynchronous mode and polling the read enabled stat enables the asynchronous detection of the event notification. For details, see poll(2) and streamio(7). Since high priority messages are used internally, perform polling for normal priority messages.

EXAMPLES

To await the termination or other status changes of the request:

	adr = NQSqwatch("-s");
	fifoname = (char *)NQSblockdata(NQSblocknext(NQSblocknext(adr)));
	sprintf(buf, "-e %s 1 BG -i %s", fifoname, reqid);
	NQSqwatch(buf);
	sprintf(buf, "-r %s", fifoname);
	NQSqwatch (buf);

NOTES

• Timing
  To detect an event that occurs only once, such as the termination of a request, confirm that the request has not been terminated after registering the terminated event, then enter the wait state. If these steps are performed inversely, it is possible to miss an event that occurs between the confirmation of the termination and event registration.

• Capacity of FIFO
  The capacity of FIFO is limited. If too many events are stored, those events which cause an overflow may be eliminated.

• Notification timeout
  If an hour has elapsed with packets remaining on FIFO, FIFO is forcibly terminated. The NQSqwatch function must be executed at least every one hour.

SEE ALSO

qwait(1),

intro(3NQS)

NAME

nqsstat - NQS data structure used by API libraries

SYNOPSIS

#include<nqsstat.h>

DESCRIPTION

nqsstat includes the structure of data which is used by the functions for getting NQS queue/request information list.

typedef long mid_t;             /* Machine-id type.             */

/* NQS information list data format */
#define NQSIDF_INT      1
#define NQSIDF_STR      2
#define NQSIDF_RESLIMIT 3

/* NQS information group ID */
#define NQSIG_BQUEATTR  1
#define NQSIG_BREQATTR  2
#define NQSIG_PPRESLIM  3
#define NQSIG_PRRESLIM  4
#define NQSIG_SCDPRMT   5

/* NQS information type ID (group 1) */
#define NQSIT1_QSTAT            000000000001
#define NQSIT1_QTYPE            000000000002
#define NQSIT1_QPRIORITY        000000000004
#define NQSIT1_QNAME            000000000010
#define NQSIT1_QDEPTCNT         000000000020
#define NQSIT1_QRUNCNT          000000000040
#define NQSIT1_QSUSPNDCNT       000000000100
#define NQSIT1_QEXITINGCNT      000000000200
#define NQSIT1_QQUEUEDCNT       000000000400
#define NQSIT1_QWAITCNT         000000001000
#define NQSIT1_QHOLDCNT         000000002000
#define NQSIT1_QARRICNT         000000004000
#define NQSIT1_QRUNLIMIT        000000010000
#define NQSIT1_QURUNLIMIT       000000020000
#define NQSIT1_QGRUNLIMIT       000000040000
#define NQSIT1_QRSG             000000100000
#define NQSIT1_QSCDPRIORITY     000000200000

/* Type of queue */
#define TQUE_BATCH       1       /* Queue is for batch requests */
#define TQUE_DEVICE      2       /* Queue is for device requests */
#define TQUE_NET         3       /* Queue is a network queue */
#define TQUE_PIPE        4       /* Queue is a pipe queue */

/* Flags of status of queue */
#define SQUE_RUNNING     0000001 /* Queue is running */
#define SQUE_ENABLED     0000002 /* Queue is enable. */

/* NQS information type ID (group 2) */
#define NQSIT2_RSEQNO           000000000001
#define NQSIT2_RMID             000000000002
#define NQSIT2_ROWNERUID        000000000004
#define NQSIT2_ROWNERNAME       000000000010
#define NQSIT2_RNAME            000000000020
#define NQSIT2_RSTAT            000000000040
#define NQSIT2_RSUBMITTIME      000000000100
#define NQSIT2_RQUEUEDTIME      000000000200
#define NQSIT2_RWAITTIME        000000000400
#define NQSIT2_RSTARTTIME       000000001000
#define NQSIT2_RENDTIME         000000002000
#define NQSIT2_RLIMITEDTIME     000000004000
#define NQSIT2_RPRIORITY        000000010000
#define NQSIT2_RJID             000000020000
#define NQSIT2_RQUENAME         000000040000
#define NQSIT2_RRERUNFLG        000000100000
#define NQSIT2_RCHKPNTFLG       000000200000
#define NQSIT2_RMAILADDR        000000400000
#define NQSIT2_RRSG             000001000000
#define NQSIT2_RSCDPRIORITY     000002000000

/* Flags of status of request */
#define SREQ_DEPARTING   0000001 /* Departing/staging-out state */
#define SREQ_RUNNING     0000002 /* Running state */
#define SREQ_STAGING     0000004 /* Staging-in state */
#define SREQ_QUEUED      0000010 /* Queued state */
#define SREQ_WAITING     0000020 /* Waiting state */
#define SREQ_HOLDING     0000040 /* Holding state */
#define SREQ_ARRIVING    0000100 /* Arriving state */
#define SREQ_CHKPOINT    0000200 /* Checkpoint state  */
#define SREQ_SUSPEND     0100000 /* Suspending state  */


/* NQS information type ID (group 2) Request rerun flag */
#define NQSIT2RRRUN_NO          1

/* NQS information type ID (group 2) Request checkpoint flag */
#define NQSIT2RCHK_NO           1

/* NQS information type ID (group 3) */
#define NQSIT3_COREFILE         000000000001
#define NQSIT3_DATA             000000000002
#define NQSIT3_FILESIZE         000000000004
#define NQSIT3_MEMORY           000000000010
#define NQSIT3_STACK            000000000020
#define NQSIT3_CPUTIME          000000000040
#define NQSIT3_FILECAP          000000000100
#define NQSIT3_OPENFILE         000000000200
#define NQSIT3_CPUNUM           000000000400

/* NQS information type ID (group 4) */
#define NQSIT4_TAPEDRV          000000000001
#define NQSIT4_MEMORY           000000000002
#define NQSIT4_CPUTIME          000000000004
#define NQSIT4_TMPFILECAP       000000000010
#define NQSIT4_FILECAP          000000000020
#define NQSIT4_FSG0             000000000040
#define NQSIT4_FSG1             000000000100
#define NQSIT4_FSG2             000000000200
#define NQSIT4_FSG3             000000000400
#define NQSIT4_OPENFILE         000000001000
#define NQSIT4_PROCESS          000000002000

/* NQS information type ID (group 5) */
#define NQSIT5_NICE             000000000001
#define NQSIT5_BASEPRIORITY     000000000002
#define NQSIT5_TIMESLICE        000000000004
#define NQSIT5_MEMORYPRIORITY   000000000010
#define NQSIT5_MODFCTCPU        000000000020
#define NQSIT5_TICKCOUNT        000000000040
#define NQSIT5_DECAYFACTOR      000000000100
#define NQSIT5_DECAYINTVL       000000000200
#define NQSIT5_MRTSIZE          000000000400
#define NQSIT5_MRTPRIORITY      000000001000
#define NQSIT5_AGINGRANGE       000000002000
#define NQSIT5_MRTMINIMUM       000000004000
#define NQSIT5_SLAVEPRIORITY    000000010000
#define NQSIT5_CPUCNT           000000020000

/* Resouce limit unit */
#define LMU_BYTES       011     /* Resource limit in bytes */
#define LMU_WORDS       012     /* Resource limit in words */
#define LMU_KBYTES      021     /* Resource limit in kilobytes */
#define LMU_KWORDS      022     /* Resource limit in kilowords */
#define LMU_MBYTES      031     /* Resource limit in megabytes */
#define LMU_MWORDS      032     /* Resource limit in megawords */
#define LMU_GBYTES      041     /* Resource limit in gigabytes */
#define LMU_GWORDS      042     /* resource limit in gigawords */

/* Flags of resource limit attribute */

#define LMF_INFINI     01   /* Extended limit is define as infinite */
#define LMF_EXPLCT      02  /* Limit is specified by user explicitly */

/* NQS information
/* length of char strings  */
#define LEN_REQLNAME    63
#define LEN_QUEUENAME   15

/* Resource limit data package */
struct nqsreslim {
    char flags;             /* Flags (QLMF_????)*/
    unsigned long max_quota;    /* Max quota limit  */
    unsigned long warn_quota;   /* Warn quota limit */
    short max_attribute;        /* units or milliseconds of max */
    short warn_attribute;       /* units of milliseconds of warn */
};

struct nqsinfoindex {
        short magic;
        short elements;
        short position;
        char *first;
        char *last;
        char *current;
};

The explanation of data included in each information list is below.

Queue name information list

As the data of NQS queue name information list, the followings are prepared.

Queue Name

Character strings (the maximum is 15 characters)

Request ID information list

As the data of NQS request ID information list, the followings are prepared.

Sequence Number

The int type numerical value

Machine ID

The mid_t type numerical value

Queue information list and Request information list

As the data of NQS queue information list and NQS request information list, the followings are prepared.

Data Format

The format of data.

Length

The length of data

Data Group ID

The group ID of data

Data Type ID

The type ID of data

Data Value

The value of data

Data Format

As the data format, the followings are prepared.

ID	Macro name	Data value type
1	NQSIDF_INT	integer (32 bit)
2	NQSIDF_STR	character strings
3	NQSIDF_RESLIMIT	resource limit struct

The resource limit struct is set as follows.

struct nqsreslim {
                char flags; /* Flags (QLMF_????)*/
                unsigned long max_quota; /* Max quota limit */
                unsigned long warn_quota; /* Warn quota limit */
                short max_attribute; /* units or milliseconds of max */
                short warn_attribute; /* units of milliseconds of warn */
};

There are three type of resource limit. Each type has the different meaning of the above struct's members.

• Ordinary type
  The resource limit specified with unit, for example, "byte" (memory size, file size, etc.).

• Time type
  The resource limit specified by time (CPU time etc.).

• Integer type
  The resource limit specified by an integer, without unit (open file number, tape drive number, etc.).

The meaning of resource limit struct members are as follows.

member name	ordinary type	time type	integer type
flags	flag	flag	flag
max_quota	max limit	max limit (seconds)	max limit
warn_quota	warn limit	warn limit (seconds)	not used
max_attribute	unit of max limit	max limit (milliseconds)	not used
warn_attribute	unit of warn limit	warn limit (milliseconds)	not used

Data Group ID

As the data group ID, the followings are prepared.

ID	Macro name	Data group name
1	NQSIG_BQUEATTR	the attributes of batch queues
2	NQSIG_BREQATTR	the attributes of batch requests
3	NQSIG_PPRESLIM	per-process resource limit
4	NQSIG_PRRESLIM	per-request resource limit
5	NQSIG_SCDPRMT	scheduling parameter

Data Type ID

As the data type ID, the followings are prepared for each data group.

Data Group 1 (The attributes of batch queues)

ID	Macro name	Data type name	Data format
000000000001	NQSIT1_QSTAT	Queue status	1
000000000002	NQSIT1_QTYPE	Queue type	1
000000000004	NQSIT1_QPRIORITY	Queue priority	1
000000000010	NQSIT1_QNAME	Queue name	2
000000000020	NQSIT1_QDEPTCNT	Departing request number	1
000000000040	NQSIT1_QRUNCNT	Running request number	1
000000000100	NQSIT1_QSUSPNDCNT	Suspended request number	1
000000000200	NQSIT1_QEXITINGCNT	Exiting request number	1
000000000400	NQSIT1_QQUEUEDCNT	Queued request number	1
000000001000	NQSIT1_QWAITCNT	Waiting request number	1
000000002000	NQSIT1_QHOLDCNT	Holding request number	1
000000004000	NQSIT1_QARRICNT	Arriving request number	1
000000010000	NQSIT1_QRUNLIMIT	Run limit	1
000000020000	NQSIT1_QURUNLIMIT	User run limit	1
000000040000	NQSIT1_QGRUNLIMIT	Group run limit	1
000000100000	NQSIT1_QRSG	RSG device file	1

The queue status is as follows.

Flag value	Macro name	Meaning of Flag
01	SQUE_RUNNING	RUNNING status
02	SQUE_ENABLED	ENABLE status

The queue type is as follows.

Flag value	Macro name	Meaning of Flag
001	TQUE_BATCH	Batch queue
002	TQUE_DEVICE	Device queue
004	TQUE_NET	Network queue
010	TQUE_PIPE	Pipe queue

Data Group 2 (The attributes of batch requests)

ID	Macro name	Data type name	Data format
000000000001	NQSIT2_RSEQNO	Sequence No.	1
000000000002	NQSIT2_RMID	Machine ID	1
000000000004	NQSIT2_ROWNERUID	User ID of the request owner	1
000000000010	NQSIT2_ROWNERNAME	Name of the request owner	2
000000000020	NQSIT2_RNAME	Request name	2
000000000040	NQSIT2_RSTAT	Status flag	1
000000000100	NQSIT2_RSUBMITTIME	Entered time	1
000000000200	NQSIT2_RQUEUEDTIME	Queued time	1
000000000400	NQSIT2_RWAITTIME	Wait time	1
000000001000	NQSIT2_RSTARTTIME	Start time	1
000000002000	NQSIT2_RENDTIME	End time	1
000000004000	NQSIT2_RLIMITEDTIME	The time since NQS refused the execution	1
000000010000	NQSIT2_RPRIORITY	Request priority	1
000000020000	NQSIT2_RJID	Job ID	1
000000040000	NQSIT2_RQUENAME	Queue name	2
000000100000	NQSIT2_RRERUNFLG	Rerun flag (-nr)	1
000000200000	NQSIT2_RCHKPNTFLG	Checkpoint flag (-nc)	1
000000400000	NQSIT2_RMAILADDR	Mail address	2
000001000000	NQSIT2_RRSG	RSG device file	1

The status flag is as follows.

Flag value	Macro name	Meaning of Flag
0000001	SREQ_DEPARTING	DEPARTING
0000002	SREQ_RUNNING	RUNNING
0000004	SREQ_STAGING	STAGING
0000010	SREQ_QUEUED	QUEUED
0000020	SREQ_WAITING	WAITING
0000040	SREQ_HOLDING	HOLDING
0000100	SREQ_ARRIVING	ARRIVING
0000200	SREQ_CHKPOINT	CHKPOINT
0100000	SREQ_SUSPEND	SUSPEND

The rerun flag is as follows.

Flag value	Macro name	Meaning of Flag
01	NQSIT2RRRUN_NO	Unable to rerun

The checkpoint flag is as follows.

Flag value	Macro name	Meaning of Flag
01	NQSIT2RCHK_NO	Unable to checkpoint

Data Group 3 (Per-process resource limit)

ID	Macro name	Data type name	Data format	Limit type
00000000001	NQSIT3_COREFILE	Core file size	3	Ordinary
00000000002	NQSIT3_DATA	Data segment size	3	Ordinary
00000000004	NQSIT3_FILESIZE	Permanent file size	3	Ordinary
00000000010	NQSIT3_MEMORY	Memory size	3	Ordinary
00000000020	NQSIT3_STACK	Stack size	3	Ordinary
00000000040	NQSIT3_CPUTIME	CPU Time	3	Time
00000000100	NQSIT3_FILECAP	Permanent file capacity	3	Ordinary
00000000200	NQSIT3_OPENFILE	Open file	3	Integer
00000000400	NQSIT3_TASKNUM	Task number	3	Integer

Data Group 4 (Per-request resource limit)

ID	Macro name	Data type name	Data format	Limit type
00000000001	NQSIT4_TAPEDRV	Tape drives	3	Integer
00000000002	NQSIT4_MEMORY	Memory size	3	Ordinary
00000000004	NQSIT4_CPUTIME	CPU time	3	Time
00000000010	NQSIT4_TMPFILECAP	Temporary file capacity	3	Ordinary
00000000020	NQSIT4_FILECAP	Permanent file capacity	3	Ordinary
00000000040	NQSIT4_FSG0	File system group 0(XMU)	3	Ordinary
00000000100	NQSIT4_FSG1	File system group 1	3	Ordinary
00000000200	NQSIT4_FSG2	File system group 2	3	Ordinary
00000000400	NQSIT4_FSG3	File system group 3	3	Ordinary
00000001000	NQSIT4_OPENFILE	Open file number	3	Integer
00000002000	NQSIT4_PROCESS	Process number	3	Integer

Data Group 5 (Scheduling parameter)

ID	Macro name	Data type name	Data format
00000000001	NQSIT5_NICE	Nice value	1
00000000002	NQSIT5_BASEPRIORITY	Base priority	1
00000000004	NQSIT5_TIMESLICE	Time slice	1
00000000010	NQSIT5_MEMORYPRIORITY	Memory priority	1
00000000020	NQSIT5_MODFCTCPU	Modification factor of CPU	1
00000000040	NQSIT5_TICKCOUNT	Tick count	1
00000000100	NQSIT5_DECAYFACTOR	Decay factor	1
00000000200	NQSIT5_DECAYINTVL	Decay interval	1
00000000400	NQSIT5_MRTSIZE	MRT size effect	1
00000001000	NQSIT5_MRTPRIORITY	MRT priority effect	1
00000002000	NQSIT5_AGINGRANGE	Aging range	1
00000004000	NQSIT5_MRTMINIMUM	MRT minimum	1
00000010000	NQSIT5_SLAVEPRIORITY	Slave priority	1
00000020000	NQSIT5_CPUCNT	CPU count	1

SEE ALSO

NQSgetquename(3NQS), NQSgetbqueattrb(3NQS), NQSgetreqid(3NQS), NQSgetreqidbyqueue(3NQS), NQSgetreqidbyuser(3NQS), NQSgetbreqattrb(3NQS), NQSinfolstnext(3NQS), NQSinfolstprev(3NQS), NQSinfolstnum(3NQS), NQSinfolstcurr(3NQS), NQSinfolstfree(3NQS), NQSinfoelmntqname(3NQS), NQSinfoelmntrimid(3NQS), NQSinfoelmntriseqno(3NQS), NQSinfoelmntatrfmt(3NQS), NQSinfoelmntatrgrp(3NQS), NQSinfoelmntatrtype(3NQS), NQSinfoelmntatrsize(3NQS), NQSinfoelmntatrintval(3NQS), NQSinfoelmntatrstrval(3NQS), NQSinfoelmntatrlimit(3NQS)