by Jeff Vance, CSY
Enhancements summary:
There are three new CI evaluator functions - JINFO, JOBCNT and WORDCNT.
There are five new CI variables - HPDATETIME, HPDOY, HPHHMMSSMMM, HPLEAPYEAR, HPYYYYMMDD.
The PAUSE command allows you to select just jobs or just sessions that match "[jobname,]user.account".
The QUOTE function, introduced late in release 5.5, has been officially removed. It was un-documented in the 6.0 base release and the function has been deleted in 6.0 Express 1. QUOTE was removed because it did not provide useful functionality, and is easy to duplicate using the existing REPL function.
The DELIMPOS function returns the position (index) of one or more specified delimiters. A defect in DELIMPOS was corrected which could impact some existing CI scripts. Prior to 6.0 express 1, DELIMPOS treated each space in the string as a separate delimiter -- in other words, there was no 'folding' of spaces. In 6.0 express 1, DELIMPOS treats multiple spaces as a single delimiter, just as the WORD function does. In fact, DELIMPOS is consistent with WORD's "endvar" parameter for all cases, except when the string has no matching delimiter. In this situation DELIMPOS returns 0, meaning there was no match; whereas, WORD returns string length plus one.
Jinfo
Syntax: JINFO ( jobID, item [,status] )
jobID Required. String identifying the target job or session that
information is being requested for. Format is "[#]J|Snnn", or
"0", indicating the current job or session..
item Required. String label specifying the information
requested for the target job or session. Only one item
can be requested per call to JINFO, although some of the items
below return multiple pieces of information.
status Optional. An unquoted CI variable name to hold the integer status
value for JINFO. If passed, the variable named by this argument
contains the status of the call to jinfo: zero indicates success,
non-zero indicates a failure. When 'status' is passed and an
error occurs, the CI ignores the error. Specifically, no message
is written to $STDLIST or to $STDERR, and the CIERROR variable is
not set. The JINFO function return is always -1 when 'status' is
specified and a JINFO error occurs. If this argument is omitted
and an error in JINFO occurs, a CI error message is written to
$STDLIST (within the definition of the HPMSGFENCE variable).
status values:
0 - success
3042 - no job or session matches the jobID
4000 - invalid syntax for the jobID, expect [#]J|Snnn
9942 - unknown JINFO item
9945 - information for the requested item is unavailable for
the target jobID
9946 - item security violation, the user needs greater
privileges to retrieve the item
Example: :calc JINFO('S64','IPaddr')
Result: 15.192.90.81
Example: :calc JINFO('J144','FmtPriority',status)
Result: DQ
Example: setvar _state JINFO(hplastjob,'jobstate',status)
while status = 0 and _state = 'WAIT' do
pause 20
...
setvar _state JINFO(hplastjob,'jobstate',status)
endwhile
Example: if jobcnt('@J:@r.sys',jlist) > 0 then
setvar i 0
setvar total_cpu 0
while setvar(_job, word(jlist,,setvar(i,i+1))) <> '' do
if JINFO(_job,'exists') then
setvar total_cpu total_cpu + JINFO(_job,'CPUsec')
endif
endwhile
endif
Restrictions
Not all items listed below are available to jobs that are waiting or scheduled. For example, JINFO is unable to return the CI PIN ('CIpin') if the job is waiting; however, some items, like the job state and job queue, are returned, regardless of the state of the target job. When a JINFO item cannot be obtained CIERR 9945 is reported. If the 'status' argument is passed, it is set to 9945 and no CI error is displayed.
No special capabilities are required to get any info about your own job/session. Users with OP or SM capability can get all items for any job/session, and may also retrieve the global items available via JINFO.
For users lacking OP or SM capability:
To access restricted data for a job logged on in the same "user.acct", AM capability is required, unless JOBSECURITY is set to LOW. If JOBSECURITY is LOW, JINFO considers the job as if it is "you".
To access restricted data for a job logged on in your account but as a different user, AM capability is required, independent of the JOBSECURITY setting.
Some items have additional restrictions:
'command', any token in the command image that could be considered a lockword is deleted.
Jinfo item values and descriptions
Label Type Description
------------- ------ --------------------------------------------------
Account string account name
CIpin int PIN number for the job's usermain process, typically
the CI
Command string * command most recently executed (lockwords are removed)
ConnectMin int number of minutes connected
ConnectSec int number of seconds connected
Copies int number of copies for $STDLIST output
CPULimit int CPU limit in seconds, -1 is unlimited
CPUMillsec int number of milliseconds of CPU
CPUSec int number of seconds of CPU
Deferred bool True if job's inpri is <= the jobfence
DegradeMode bool *+ True if system is running in degraded mode, meaning no
new jobs are allowed to log on until disk space is recovered
Exist bool True if the target job exists in any state
Exists bool See 'Exist'
Executing bool ! True if the target job exists and is in the INTRO,
EXEC* or EXEC states
FmtIntroDate string formatted date job was introduced, eg.
"WED, JUL 14, 1999"
FmtIntroTime string formatted time job was introduced, eg. "6:21 PM"
FmtPriority string current scheduling queue for the usermain (CI) process,
e.g. 'BS', 'CS', 'DS', 'ES'
FmtStreamedByDate string formatted date when job/session was submitted
FmtStreamedByTime string formatted time when job/session was submitted
Group string logon group name
HomeGroup string * home group name
Inpri int input priority
IntIntroDate int date job was introduced as a YYYYMMDD integer
IntIntroTime int time job was introduced as a HHMMSS integer
IntroDate int see "IntIntroDate"
IntroTime int see "IntIntroTime"
IntStreamedByDate int date job/session was submitted as a YYYMMDD integer
IntStreamedByTime int time job/session was submitted as a HHMMSS integer
IPAddr string ** IP address in dotted format (xx.xx.xx.xx), '' for
jobs and local sessions
Job User Account string "[jname,]user.acct" names concatenated
Job User Account string "[jname,]user.acct,group" names concatenated
Group
JobName string jobname if supplied, else ""
JobNum string unique job identifier, "#J|Snnn"
JobQ string job queue name, "" for sessions
JobSecurity bool *+ 'LOW' or 'HIGH' depending on the JOBSECURITY setting
JobState string "INTRO", "SCHED", "WAIT", "EXEC*", "EXEC", "SUSP"
JobType string "J" for jobs and "S" for sessions
JobUserAccount string see "Job User Account".
JobUserAccountGroup string see "Job User Account Group"
JSMAINPin int PIN number for the job's JSMAIN process
LdevIn int Input LDEV number for $STDIN
LdevOut int Output LDEV number for $STDLIST, 0 for spooled jobs
LocAttr int * user local attributes
Numbered bool True is job file is numbered
Outclass string Outclass name for a job's STDLIST, e.g. "LP". Empty
("") for sessions
Outpri int output priority
PassExempt string *+ the system's password exemption policy for jobs:
"NONE", "USER", "XACCESS", "MAX"
Priority int current priority for the usermain (CI) process, e.g.
150, 200, etc.
Private bool * True if the job's stdlist is marked private
Quiet bool True if :set msg=off is in effect
RawIntroDate int date job was introduced in CALENDAR format
RawIntroTime int time job was introduced in CLOCK format
RawStreamedByDate int date job/session was submitted in CALENDAR format
RawStreamedByTime int time job/session was submitted in CLOCK format
Restart bool True if ";RESTART" specified in job "card"
Scheduled bool ! True if the target job exists and is in the SCHED state
State string see "JobState"
StdinSPID string "Innn" identifier for the stdin spoolfile for jobs
StdinSPstate string STDIN spoolfile state: "OPEN", "ACTIVE", "READY".
"" for sessions
StdlistDelete bool True if SET STDLIST=delete in effect
StdlistSPID string "Onnn" identifier for the stdlist spoolfile for jobs
"" for sessions
StdlistSPstate string STDLIST spoolfile state: "CREATE", "DEFER", "READY",
"XFER", "PRINT", "PROBLM", "DELPND", "SPSAVE".
Note: some of these states apply to jobs that have
terminated. No JINFO information is available on jobs
that have terminated
StreamedBy string * full identifier of the job/session that streamed
or initiated the target job. For example:
"jobname,user.account (#J123)". This is the same
value as seen in the HPSTREAMEDBY CI variable
StreamedByDate int see "IntStreamedByDate"
StreamedByLdev int * Ldev of job/session that submitted the target job
StreamedByTime int see "IntStreamedByTime"
Suspended bool ! True if the target job exists and is in the SCHED state
User string user name
User Account string "user.account" names concatenated
User Account string "user.account,group" names concatenated
Group
UserAccount string See "User Account"
UserAccountGroup string See "User Account Group"
Waiting bool ! True if the target job exists and is in the WAIT state
* indicates you must have SM or OP capabilities, or the job must be your own
job, or you must have AM capability and be logged on into the same account
as the target job, or you must be logged on as the same user.account as the
target job and JOBSECURITY is LOW. Otherwise, the item is not returned and
an error is generated.
*+ indicates you must have SM or OP capabilities.
** indicates you must have one of SM,OP,NA,NM,PM capabilities.
! indicates a feature new to 7.0 express 1.
Jobcnt
Syntax: JOBCNT ( job_match [,joblist_var] )
Defn: A CI evaluator function that returns the number of jobs and/or
sessions that match 'job_match'. Optionally, these matching
job/session numbers are returned in the CI variable named by
the 'joblist_var' parameter. All jobs/sessions matching
"job_match" are counted, including: executing, waiting, suspended
and scheduled jobs.
Type: Integer.
Parms
Job_match: Required. String identifying the target jobs and/or sessions.
Supported formats:
"@" - all jobs and sessions
"@J" - all jobs
"@S" - all sessions
"user.acct" - all job/sessions matching "user.acct"
"jobname,user.acct" - all job/sessions matching
"jobname,user.acct"
"@J:[jobname,]user.acct" - all jobs-only matching
"[jobname,]user.acct"
"@S:[jobname,]user.acct" - all sessions-only matching
"[jobname,]user.acct"
Note: "jobname", "user" and "acct" may be wildcarded.
Note: ",user.acct" (empty 'jobname') can be passed to specify
that only jobs or sessions without job names are desired.
If 'jobname' is specified then only job/sessions with
job names are considered.
Joblist_var: Optional. An unquoted name of a CI variable that holds the
job/session numbers that match the 'job_match' argument. Each
job/session number is separated by a single space. For example:
"J2 S34 S36 J12 J31 S44"
Note: it is possible that more jobs match than will fit
in the CI variable. In this event, the variable is
filled to capacity without reporting an error. The
caller can detect this condition by comparing the
number of jobs matching against the number of tokens
in the 'joblist_var' variable.
Example: :calc JOBCNT("@S") # find all sessions
Result: 12
Example: :calc JOBCNT("@J:@.sys") # find all jobs in SYS account
Result: 4
Example: setvar x JOBCNT('@', jlist) # find all jobs/sessions
if x <> wordcnt(jlist) then
# not all matching job/sessions fit into var
...
Example: :calc JOBCNT("@!hpjobtype:!hpjobname,!hpuser.!hpaccount")
Result 1 # find all jobs or sessions logged
# on exactly as "you"
Wordcnt
Syntax: WORDCNT ( string[,delims][,start] )
Defn: A CI evaluator function that returns the number or words
(tokens) defined by "delims" in "string", starting at
"start". The default delimiters are the same as for the
WORD and DELIMPOS functions: a space, a comma, a semicolon,
an equals sign, left and right parentheses, left and right
brackets, single quote, double quote, and tab. The default
start is 1.
Type: Integer
Example: :calc WORDCNT('file a=bb,old;rec=40,,f,ascii')
Result: 9
New CI variables
HPDATETIME A CI variable containing the current date and time in a string
formatted as "YearMonthDateHourMinuteSecondMillisecond". For
consistency, if HPDATETIME is referenced more than once for a
"logical" (or atomic) operation, such as extracting the date and
the time, it is very important to store HPDATETIME into a
user-defined variable and extract from that variable. For example,
to accurately separate the date and time from HPDATETIME the code
below should *NOT* be used:
setvar mydate lft(hpdatetime,8) /* Don't do this! */
setvar mytime rht(hpdatetime,9) /* Don't do this! */
The problem above is that "MYDATE" could be set a millisecond
before midnight, and "MYTIME" could be set a millisecond past
midnight, with the result being:
MYDATE = 19990314 /* Mar 14 just before midnight */
MYTIME = 000000100 /* Mar 15 just past midnight */
Instead, create a variable that contains HPDATETIME and extract
from that variable. For example:
setvar date_time HPDATETIME /* This is correct! */
setvar mydate lft(date_time,8)
setvar mytime rht(date_time,9)
Note: current time resolution is only tenths-of-a-second so the
last two string characters will both be "0".
Type: String, read-only.
Example: if the current date and time is Feb 21, 1999 at
14:08:15:2, HPDATETIME equals "19990221140815200"
HPDOY A CI variable containing the day number in the current year, with
Jan. 1 being day 1.
Type: Integer, read-only.
Example: On Feb, 7, 1999 HPDOY equals: 38
HPHHMMSSMMM A CI variable containing the current time in a string formatted as
"HourMinuteSecondMillisecond". Note: current resolution is only
tenths-of-a-second so the last 2 string characters will both be
"0".
Type: String, read-only.
Example: if the current time is 14:08:15:2, HPHHMMSSMMM equals
"140815200"
HPLEAPYEAR A CI variable that indicates if the current year is a leap year.
Type: Boolean, read-only.
Example: On Feb. 7, 1999 HPLEAPYEAR equals: FALSE
On Jan. 1, 2000 HPLEAPYEAR equals: TRUE
HPYYYYMMDD A CI variable containing the current date in a string formatted as
"CenturyYear-of-centuryMonthDate".
Type: String, read-only.
Example: if the current date is Feb 21, 1999, HPYYYYMMDD equals
"19990221"
Pause enhancement
PAUSE - The JOB= parameter of the PAUSE command now allows users to select
jobs-only or sessions-only in the target user.account(s). A new
"@J:" or "@S:" prefix to the existing "[jobname,]user.account" form
supports this new functionality. The complete syntax for JOB= is:
[#]J|Snnnn, where nnn is a number, or
@S|@J|@ or
[@J|@S:][jobname,]user.acct
The 'jobname' value can be passed as an null value (",") to
indicate that only jobs or sessions without jobnames are considered.
A non-null value in 'jobname' means that only jobs or session with
job names are candidates for selection. If 'jobname' is not
relevant to the selection then it should be omitted, and only the
'user.acct' should be specified.
To pause until all job/sessions logged on exactly as "you"
(but excluding "you") terminate, enter:
:pause job="@!hpjobtype:!hpjobname,!hpuser.!hpaccount
|
