The Number Counter tool provides the best performing solution for the
case where a consecutive number must be assigned for multiple jobs.
For example, the NBRCTR tool should be considered if multiple
operators are entering orders and each order should be assigned the
next consecutive number.
The NBRCTR function uses the MI COMPSWAP instruction which allows it
to assign a number without locking an object. Note that the COMPSWAP
instruction will operate correctly on a system with multiple CPUs.
The control values are kept in a user space which must be created by
the CRTNBRCTR command. The values can also be changed by the
CHGNBRCTR command.
A typical CRTNBRCTR command would be:
CRTNBRCTR NBRCTR(LIB1/CTR1)
This creates a user space by the name of CTR1 in LIB1. Since no
other parameters were specified, the counter would start at 1 and
have a maximum value of 4,294,967,250.
The normal solution for accessing the next consecutive number would
be to call the processing program TAANBRBR directly. A RTVNBRCTR
command is also available.
A typical series of commands for RTVNBRCTR would be:
DCL &RTNNBR *DEC LEN(10 0)
.
RTVNBRCTR COUNTER(LIB1/CTR) RTNNBR(&RTNNBR)
The &RTNNBR value would be the next number and would be unique across
the system.
To call the program TAANBRBR from a HLL program, three parameters
must be passed.
ACTION *CHAR LEN(4) Pass *STD, *GET, or *END
QLFSPC *CHAR LEN(20) Pass user space and library
RTNNBR *DEC LEN(10 0) Return number
The ACTION parameter should be passed as *GET or *STD when the next
number is needed. *STD causes the number to be returned and LR to be
set on. *GET causes the number to be returned and the TAANBRBR
program remains active waiting for the next call (the program returns
with LR off). If *GET is used for repeated accesses, *END should be
passed when no number should be returned and the program should be
ended (the program returns with LR on).
The QLFSPC parameter should be the name of the Number Counter (user
space) that was created by CRTNBRCTR in the format:
1 - 10 Number counter name
11 - 20 Number counter library
The following is an example of RPG III code:
C CALL 'TAANBRBR' Get nbr ctr
C PARM ACTION 4 Action
C PARM QLFSPC 20 Qlf space
C PARM RTNNBR 100 Rtn number
NBRCTR Options
--------------
The NBRCTR function provides several options:
** You can specify an initial value. The default is 1. This
will be the first number returned by RTVNBRCTR. The number
must be 1 or greater (a 0 is never returned).
** You can decide on a maximum value that will be allowed. For
example, if you have a 6 digit Order Number, you would want a
maximum value of 999,999 or less.
The maximum value that is allowed is 4,294,967,250. This is a
few numbers short of the maximum value in a 4 byte unsigned
field (the COMPSWAP instruction is limited to 4 bytes). The
return value is always a 10 digit packed decimal field.
** If the maximum is exceeded, you have a choice of sending an
escape message or 'wrapping' the counter meaning that the next
number assigned would be your initial value.
Using the default, an escape message would be sent to any job
that attempts to go beyond the maximum.
** You can specify a 'threshold value', 'threshold increment',
and a 'threshold message queue' For example, if you want a
warning that you are approaching a 6 digit maximum, you could
request a threshold of 900,000 and a threshold increment of
10,000. If the threshold is exceeded, a message is sent to
the message queue you specified (default is QSYSOPR). After
the threshold is exceeded, the threshold increment is added to
the threshold value to allow warning messages to be sent after
each 10,000 increment is reached.
The options are kept as data within the user space. They should only
be changed by the CHGNBRCTR command.
Security considerations
-----------------------
The default for CRTNBRCTR is to create a *USRSPC object with *PUBLIC
having *USE authority. The RTVNBRCTR command adopts the program
owner's authority to allow the *PUBLIC user to update the number
counter using the supplied interface.
All NBRCTR commands are set for *PUBLIC to have *USE authority.
The CHGNBRCTR command can only be used by a user with *OBJMGT
authority to the Number Counter.
The ADDNBRCTR and DLTNBRCTR commands require a user with *OBJEXIST
authority to the Number Counter.
Because a *USRSPC object is created, there is nothing to prevent a
user from operating directly on the user space with TAA User Space
commands or APIs. 'Read only' functions will not impact the
integrity of the application.
System security is used to prevent a non-authorized user from
updating the user space other than thru the supplied RTVNBRCTR
function.
The owner of the *USRSPC can perform any function on the user space.
Normal authorization functions will allow other users to operate on
the user space. To ensure application integrity, only the NBRCTR
commands should be used on a Number Counter.
Abnormal system termination considerations
------------------------------------------
When the COMPSWAP instruction runs, the value in the user space is
changed. Normal system paging will write the updated value to disk.
If the system terminates normally, the correct value will exist.
However, if the system abnormally terminates, there is no guarantee
that the user space has been updated on disk with the last use of
COMPSWAP. There is also no guarantee that a job actually wrote a
record to disk based on the number that was retrieved (it is possible
that a 'gap' in the consecutive numbers will exist).
Good programming practice would be to provide a program that runs
only on an abnormal termination (before starting any other
subsystems) that will determine the last value that was used based on
the last data base record in a file. This value would be bumped by
one and the CHGNBRCTR command used to provide a new initial value.
This type of program could be called from a Start up program (see the
QSTRUPPGM system value) and would use the QABNORMSW system value to
determine if an abnormal termination had occurred.
A manual solution is provided with the ADDNBRCTR command. You can
use it to bump the number counter so that the next value to be
assigned will be in synch with the last record found in the data
base.
NBRCTR Commands
--------------
Several commands are provided:
CRTNBRCTR Create number counter
RTVNBRCTR Retrieve number counter
May call directly with TAANBRBR
DSPNBRCTR Display number counter
CHGNBRCTR Change number counter
A prompt override program exists
RTVNBRCTRD Retrieve number counter description
ADDNBRCTR Adds a number (intended for synchronization)
DLTNBRCTR Delete number counter
DMONBRCTR Demo number counter - Builds a file
DMONBRCTR2 Demo number counter 2 - Analyzes file
Demo Function
-------------
To assist you in understanding the NBRCTR function and in testing it,
two DMO commands are provided.
To use the DMO function, you must first create a number counter with
the options you want to test:
CRTNBRCTR NBRCTR(xxx) ...
You then enter the DMONBRCTR command to submit multiple batch jobs.
The concept is that the batch jobs run simultaneously (default is to
submit to QINTER), to demonstrate how multiple jobs can use the
NBRCTR function at the same time.
DMONBRCTR NBRCTR(xxx) NBRACCS(nnn) NBRJOBS(nnn)
With DMONBRCTR, you describe the number of accesses you want each
batch job to use (the number of RTVNBRCTR functions) and how many
batch jobs should run.
The output of these batch jobs is to write a record in the DMONBRCTR
file in TAAWORK. Each job will output records until the number
specified for NBRACCS is reached.
The DMONBRCTR2 command analyzes the file to ensure that all numbers
are unique and no gaps exist. The command has no parameters and is
entered as:
DMONBRCTR2
Completion messages from the command describe how to view the file
for your own satisfaction.
If your system has a single CPU, each job shares the CPU for a given
amount of time (based on the Job's Class Timeslice). Consequently,
you will see bursts of consecutive numbers retrieved from each job
that is running.
Because the output file is written in blocks of records (not one
record at a time), you will see blocks of consecutive records from
each batch job written to the DMONBRCTR file. If the data is
displayed in physical sequence, the consecutive number field will not
be in sequence.
When you are completed testing, delete the file:
DLTF FILE(TAAWORK/DMONBRCTR)
Each use of DMONBRCTR clears the TAAWORK/DMONBRCTR file.
It is possible to use CHGNBRCTR while the batch jobs are running. To
simulate a real condition, do the following:
** Use CHGNBRCTR with values such as INLVAL(1000000) and
MAXVAL(2000000).
** Use DMONBRCTR
** While the batch jobs are running, use CHGNBRCTR and specify
INLVAL(1). This simulates what you might do if you were
receiving threshold messages and want to reset the initial
value while users are using RTVNBRCTR. The next number
assigned will start at 1.
** After the batch jobs complete, use DMONBRCTR2. It should show
that there is a gap with the first gap number as 1000000.
NBRCTR escape messages you can monitor for
------------------------------------------
None of the commands produce error messages that are intended to be
monitored for. Escape messages from based on functions will be
re-sent.
CRTNBRCTR Command parameters *CMD
----------------------------
CRTNBRCTR creates the Number Counter.
NBRCTR The qualified name of the Number Counter to be
created. The library value defaults to *CURLIB.
A 'Number Counter' is created as a *USRSPC object.
The values are placed in the user space. The
*PUBLIC is given *USE authority. The RTVNBRCTR
command adopts authority to allow the *PUBLIC to
update the user space.
INLVAL The initial value to be used. This will be the
first number returned. The default is 1.
MAXVAL The maximum value to be returned. The default is
*MAX which produces the maximum value of
4,294,967,250.
If the maximum is exceeded, the counter will wrap
back to your initial value if WRAP(*YES) is
specified. If WRAP(*NO) is specified, an escape
message will be sent to each job that attempts to
retrieve a number greater than the maximum.
THRVAL The threshold value to be used to determine when a
message is sent to the threshold message queue. The
default is *NONE, meaning no threshold message will
be sent.
If a value is entered, it must be greater than the
initial value and less than the maximum value. If
the threshold is exceeded, an 'information message'
is sent to the specified threshold message queue.
If WRAP(*YES) is specified, THRVAL(*NONE) must be
used.
THRINC The threshold increment value to be used after the
threshold value is exceeded. The default is *NONE.
The intent of THRINC is to provide additional
messages as the maximum value is approached. For
example, if the threshold value is 900 and is
exceeded, a message is sent. If 10 is used for the
threshold increment value, additional messages would
be sent when the counter exceeds 910, 920, 930, etc.
THRMSGQ The qualified message queue assigned for threshold
messages. The default is QSYSOPR in QSYS. No
messages are sent unless a value is provided for
THRVAL. The message queue must exist.
If QSYSOPR in QSYS is specified and QSYSMSG also
exists in QSYS, the same message is sent to QSYSMSG.
WRAP Whether to 'wrap' the number counter if the maximum
is exceeded. The default is *NO meaning each job
which requests a number greater than the maximum
would receive an escape message.
*YES may be specified to reset the number counter to
the INLVAL parameter value (this value may also be
changed by the CHGNBRCTR command). No message
occurs when the counter is 'wrapped'.
TEXT The text description of the number counter. The
default is *DFT meaning that standard text is
provided.
RTVNBRCTR Command parameters *CMD
----------------------------
RTVNBRCTR retrieves the unique next number from a Number Counter.
NBRCTR The qualified name of the Number Counter to be
retrieved from. The library value defaults to
*LIBL.
The Number Counter must have been created by the TAA
CRTNBRCTR command.
ACTION Whether to return a number and keep the program
active or to end the program. The default is *STD
which causes the program to return the next number
and LR to be set on.
*GET causes the next number to be returned, but LR
is not set on which allows the program to remain
active. This provides better performance the next
time the function is needed in the same job.
If *GET is used for repeated accesses, *END may be
specified when the program is no longer needed in
the job. Note that when *END is used, the RTNNBR
parameter is not updated. The program does an
immediate end (LR is set on).
If the job ends without using ACTION(*END), the
system cleans up the program and the user space will
be properly updated on disk. See the tool
documentation for a discussion of Abnormal System
Termination.
RTNNBR The return number if ACTION = *STD or *GET. This
must be declared as *DEC LEN(10 0) (a packed field
is returned).
A 0 value is never returned.
RTVNBRCTRD Command parameters *CMD
------------------------------
RTVNBRCTRD retrieves the description values that were entered on
CRTNBRCTR (they can be changed by CHGNBRCTR).
NBRCTR The qualified name of the Number Counter to be
retrieved from. The library value defaults to
*LIBL.
The Number Counter must have been created by the TAA
CRTNBRCTR command.
RTNLIB The library name where the Number Counter exists.
This is an optional return variable that if used
must be declared as *CHAR LEN(10).
The value may be helpful if *LIBL is used as the
qualified name for the Number Counter.
NXTNBR The next number to be assigned. This is an optional
return variable that if used must be declared as
*DEC LEN(10 0).
Retrieving this value does not cause a change in the
next number to be assigned.
RTNINLVAL The initial value that is specified for the Number
Counter. This is an optional return variable that
if used must be declared as *DEC LEN(10 0).
RTNMAXVAL The maximum value that is specified for the Number
Counter. This is an optional return variable that
if used must be declared as *DEC LEN(10 0).
RTNTHRVAL The threshold value that is specified for the Number
Counter. This is an optional return variable that
if used must be declared as *DEC LEN(10 0).
If *NONE was specified, a 0 will be returned.
RTNTHRINC The threshold increment value that is specified for
the Number Counter. This is an optional return
variable that if used must be declared as *DEC
LEN(10 0).
If *NONE was specified, a 0 will be returned.
RTNTHRMSGQ The threshold message queue value that is specified
for the Number Counter. This is an optional return
variable that if used must be declared as *CHAR
LEN(10).
RTNTHRMSGL The threshold message queue library value that is
specified for the Number Counter. This is an
optional return variable that if used must be
declared as *CHAR LEN(10).
RTNWRAP The 'wrap' value that is specified for the Number
Counter. This is an optional return variable that
if used must be declared as *CHAR LEN(4). A *YES or
*NO will be returned.
RTNTEXT The text description value that is specified for the
Number Counter. This is an optional return variable
that if used must be declared as *CHAR LEN(50).
DSPNBRCTR Command parameters *CMD
-----------------------------
DSPNBRCTR displays the values that were entered on CRTNBRCTR (they
can be changed by CHGNBRCTR).
NBRCTR The qualified name of the Number Counter to be
displayed. The library value defaults to *LIBL.
The Number Counter must have been created by the TAA
CRTNBRCTR command.
OUTPUT How to output the results. The default is * meaning
that if the command is entered in the interactive
environment, a display will appear.
If in batch or *PRINT is specified, a spooled file
is output.
CHGNBRCTR Command parameters *CMD
----------------------------
CHGNBRCTR allows changes to the values that were entered on
CRTNBRCTR.
Each parameter value defaults to *SAME meaning the existing value
will be retained.
A prompt override program exists so that if the command is entered
with a Number Counter name and F4 is used, the existing values will
be displayed.
Caution must be taken with the INLVAL parameter. If the prompt
override program is used, the value is still shown as *SAME. If a
value (or *RESET) is specified, the next number retrieved by
RTVNBRCTR will be the new value.
It is valid to use CHGNBRCTR while other users are using RTVNBRCTR on
the same Number Counter. No locking occurs while using CHGNBRCTR to
allow a dynamic change to occur. The command will prevent two users
from using CHGNBRCTR at the same time on the same Number Counter.
The command will attempt to ensure that a valid change is being made.
However, there are situations where the use of CHGNBRCTR being used
at the same time numbers are being retrieved can lead to errors.
NBRCTR The qualified name of the Number Counter to be
changed. The library value defaults to *LIBL.
INLVAL The initial value to be used. This will be the
first number returned. The default is *SAME meaning
no change will occur.
Caution must be taken with the INLVAL parameter. If
the prompt override program is used, the value is
still shown as *SAME. If a value (or *RESET) is
specified, the next number retrieved by RTVNBRCTR
will be the new value.
If *RESET is specified, the existing initial value
is used to reset the current number. For example,
if you had used INLVAL(1) for CRTNBRCTR and the next
number to be assigned is 502, using *RESET will
cause the next number to be assigned to be 1.
A specific number may be entered as a new initial
value. This will cause the next number to be
assigned to be the value you specified.
MAXVAL The maximum value to be returned. The default is
*SAME meaning no change will occur. The maximum
value that may be entered is 4,294,967,250.
If the maximum is exceeded, the counter will wrap
back to your initial value if WRAP(*YES) is
specified. If WRAP(*NO) is specified, an escape
message will be sent to each job that attempts to
retrieve a number greater than the maximum.
THRVAL The threshold value to be used to determine when a
message is sent to the threshold message queue. The
default is *SAME meaning no change will occur.
*NONE may be entered which means no threshold
message will occur. If *NONE is entered, the THRINC
value is assumed to be *NONE.
If a value is entered it must be greater than the
next number to be assigned and less than the maximum
value. If the threshold is exceeded, an
'information message' is sent to the specified
threshold message queue.
If WRAP(*YES) is specified, THRVAL(*NONE) must be
used.
THRINC The threshold increment value to be used after the
threshold value is exceeded. The default is *SAME.
The intent of THRINC is to provide additional
messages as the maximum value is approached. For
example, if the threshold value is 900 and is
exceeded, a message is sent. If 10 is used for the
threshold increment value, additional messages would
be sent when the counter is at 910, 920, 930, etc.
If THRVAL(*NONE) is specified, the value of THRINC
is assumed to be *NONE.
THRMSGQ The qualified message queue assigned for threshold
messages. The default is *SAME. No messages are
sent unless a value is provided for THRVAL. The
message queue must exist.
If QSYSOPR in QSYS is specified and QSYSMSG also
exists in QSYS, the same message is sent to QSYSMSG.
WRAP Whether to 'wrap' the number counter if the maximum
value is exceeded. The default is *SAME.
If *NO is specified and the maximum value is
exceeded, an escape message is sent to the job
requesting the next number.
*YES may be specified to reset the number counter to
the INLVAL parameter value. No message occurs when
the counter is 'wrapped'.
TEXT The text description of the number counter. The
default is *SAME.
A new text description may be entered.
ADDNBRCTR Command parameters *CMD
----------------------------
ADDNBRCTR adds an amount to an existing Number Counter. You must
have *OBJEXIST rights to the Number Counter to use ADDNBRCTR. The
command is intended as a synchronization function to allow a manual
correction following an abnormal system termination. By adding an
amount, you can synchronize the last data base record and the number
counter.
NBRCTR The qualified name of the Number Counter to be added
to. The library value defaults to *LIBL.
The Number Counter must have been created by the
CRTNBRCTR command.
AMT The amount to add to the Number Counter. The
default is 1. It must be a number between 1 and
99999.
DLTNBRCTR Command parameters *CMD
----------------------------
DLTNBRCTR deletes an existing Number Counter.
NBRCTR The qualified name of the Number Counter to be
deleted. The library value defaults to *LIBL.
The Number Counter must have been created by the
CRTNBRCTR command.
DMONBRCTR Command parameters *CMD
----------------------------
DMONBRCTR provides a demonstration of the NBRCTR function. The
demonstration occurs by submitting a user specified number of batch
jobs. Each batch job uses the RTVNBRCTR function a specified number
of times. Each time a number is retrieved, a record is added to the
DMONBRCTR file in the TAAWORK library. This file is created by
DMONBRCTR before the batch jobs are submitted. If the file already
exists, the data is cleared.
After the batch jobs complete, analyze the output with the the
DMONBRCTR2 command.
NBRCTR The qualified name of the Number Counter to be used
in the demonstration. You must create the Number
Counter using CRTNBRCTR. The library value defaults
to *LIBL.
NBRACCS The number of RTVNBRCTR accesses that will be made
from each job that is submitted. The default is
10,000. The value must be between 1 and 1,000,000.
Each access causes a record to be written to the
DMONBRCTR file in the TAAWORK library.
NBRJOBS The number of batch jobs to be submitted. The
default is 5. The value must be between 1 and 25.
Providing multiple jobs provides a reasonable test
of the function of different jobs retrieving the
next number from the number counter.
Each job will have a name of NBRCTRnn where nn is a
consecutive number.
JOBQ The qualified name of the job queue to be used.
QINTER is the default.
The intent of using QINTER is to allow multiple jobs
to be active at the same time that are making
requests for the next number from the number
counter.
The library name defaults to *LIBL.
DMONBRCTR2 Command parameters *CMD
-----------------------------
DMONBRCTR2 provides an analysis of the DMONBRCTR file in TAAWORK.
The file is sequenced by the number that was retrieved from the
RTVNBRCTR function. The data is checked to ensure there are no
duplicates and no gaps (consecutive numbers must exist). A summary
of the file is output to a spooled file.
The command has no parameters.
Restrictions
------------
** See the section describing the number counter following an
abnormal system termination.
** Only the TAA Commands for NBRCTR should be used to create and
maintain the user space used as a NBRCTR.
** Multiple users should not use CHGNBRCTR at the same time on
the same Number Counter.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHGUSRSPC Change user space
CHKOBJ3 Check object 3
CRTUSRSPC Create user space
CVTBIN8 Convert from binary 8
CVTTOBIN8 Convert to binary 8
DUPFILFMT Duplicate file format
EDTVAR Edit variable
RTVSYSVAL3 Retrieve system value 3
RTVUSRSPC Retrieve user space
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
Implementation
--------------
The tool is ready to use, but you must first create a Number Counter
with the CRTNBRCTR command.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVNBRCTR *CMD TAANBRB QATTCMD
CRTNBRCTR *CMD TAANBRB2 QATTCMD
RTVNBRCTRD *CMD TAANBRB3 QATTCMD
DSPNBRCTR *CMD TAANBRB4 QATTCMD
CHGNBRCTR *CMD TAANBRB5 QATTCMD
DLTNBRCTR *CMD TAANBRB6 QATTCMD
DMONBRCTR *CMD TAANBRB7 QATTCMD
DMONBRCTR2 *CMD TAANBRB8 QATTCMD
ADDNBRCTR *CMD TAANBRB9 QATTCMD
TAANBRBC *PGM CLP TAANBRBC QATTCL
TAANBRBC2 *PGM CLP TAANBRBC2 QATTCL
TAANBRBC3 *PGM CLP TAANBRBC3 QATTCL
TAANBRBC4 *PGM CLP TAANBRBC4 QATTCL
TAANBRBC5 *PGM CLP TAANBRBC5 QATTCL
TAANBRBC6 *PGM CLP TAANBRBC6 QATTCL
TAANBRBC7 *PGM CLP TAANBRBC7 QATTCL
TAANBRBC8 *PGM CLP TAANBRBC8 QATTCL
TAANBRBC9 *PGM CLP TAANBRBC9 QATTCL
TAANBRBC15 *PGM CLP TAANBRBC15 QATTCL
TAANBRBC17 *PGM CLP TAANBRBC17 QATTCL
TAANBRBC18 *PGM CLP TAANBRBC18 QATTCL
TAANBRBR *PGM RPG TAANBRBR QATTRPG
TAANBRBR4 *PGM RPG TAANBRBR4 QATTRPG
TAANBRBR8 *PGM RPG TAANBRBR8 QATTRPG
TAANBRBR17 *PGM RPG TAANBRBR17 QATTRPG
TAANBRBD *FILE DSPF TAANBRBD QATTDDS
TAANBRBP *FILE PF TAANBRBP QATTDDS
The TAANBRBP file exists in TAATOOL. It is used as a model to create
the DMONBRCTR file in TAAWORK.
Structure
---------
RTVNBRCTR Cmd
TAANBRBC CL pgm
TAANBRBR RPG ILE Pgm
CRTNBRCTR Cmd
TAANBRBC2 CL pgm
RTVNBRCTRD Cmd
TAANBRBC3 CL pgm
DSPNBRCTR Cmd
TAANBRBC4 CL pgm
TAANBRBD Dsp file
TAANBRBR4 RPG program for printed output
CHGNBRCTR Cmd
TAANBRBC5 CL pgm
TAANBRBC15 is prompt override CL pgm
DLTNBRCTR Cmd
TAANBRBC6 CL pgm
DMONBRCTR Cmd
TAANBRBC7 CL pgm
Submits TAANBRBC17 CL pgm
TAANBRBR17 RPG pgm writes to DMONBRCTR file
DMONBRCTR2 Cmd
TAANBRBC8 CL pgm
TAANBRBR8 RPG pgm
TAANBRBC18 CL pgm Does RTVNBRCTRD
ADDNBRCTR Cmd
TAANBRBC9 CL pgm
|
