This document covers the following topics:
Format/length: | A8 |
Content modifiable: | No |
This system variable contains the ID of the library to which the user is currently logged on.
Format/length: | A32 |
Content modifiable: | No |
If Natural Security is installed, this system variable contains the
name of the library to which the user is logged on. If the user is logged on
via a special link, it contains the link name instead. If Natural Security is
not installed, this system variable contains the name SYSTEM
.
The general option Set *APPLIC-NAME always to library
name
can be set so that *APPLIC-NAME
always
contains the library name, regardless of whether the user is logged on via a
special link or not. See
Set *APPLIC-NAME always to library
name in the Natural Security
documentation.
Format/length: | A128 |
Content modifiable: | Yes |
This system variable designates a communication area which can be used to process data from outside a screen window.
Normally when a window is active, no data can be entered on the
screen outside the window. However, if a map contains
*COM
as a modifiable field, that field will still
be available for the user to enter data when a window is currently on the
screen. Further processing can then be made dependent on the content of
*COM
. This allows you to implement user interfaces
where a user can always enter data in the command line, even when a window with
its own input fields is active.
Note:
Although *COM
can be used as a
modifiable field in an INPUT
statement, it is
not treated as an input field, but as a system variable; that is, any
input entered into the *COM
field will be taken as
it is, without any input processing (e.g. conversion to upper case) being
performed on it. Once *COM
has been displayed on
the screen via an INPUT
statement, every subsequent
INPUT
or REINPUT
statement will cause
the current content of *COM
to be
displayed.
See also:
Dialog Design in the Programming Guide
Format/length: | I4 |
Content modifiable: | Yes |
This system variable contains the conversation ID of the current
conversational remote procedure call (RPC). This ID is set by an
OPEN CONVERSATION
statement.
Via an OPEN CONVERSATION
statement, a client can get a
server for exclusive use to execute a number of services (subprograms) within
one server process. This exclusive use is called conversation. The OPEN
CONVERSATION
statement is used to open a conversation and specify the
subprograms to be involved in this conversation. When an OPEN
CONVERSATION
statement is executed, it assigns a unique ID which
identifies the conversation to the system variable
*CONVID
.
Several conversations can be open at the same time. To switch from
one open conversation to another, you assign the corresponding conversation ID
to *CONVID
.
For further information on Natural RPC, see the Natural RPC (Remote Procedure Call) documentation.
Format/length: | P10 |
Content modifiable: | Yes |
This system variable contains the number of times a processing loop
initiated by a FIND
,
READ
,
HISTOGRAM
or
PARSE
statement has
been entered.
(r)
notation after *COUNTER
is used to
indicate the statement label or source-code line number of the
FIND
, READ
, HISTOGRAM
or
PARSE
statement. If (r)
is
not specified, *COUNTER
represents the number of
times the currently active processing loop has been entered.
*COUNTER
is not incremented if a record
is rejected as a result of the criteria specified in a WHERE
clause. *COUNTER
is incremented if a record is
rejected as a result of an ACCEPT
/REJECT
statement.
Format/length: | I4 |
Content modifiable: | No |
*CPU-TIME
contains the CPU time
currently used by the Natural process in units of 10 ms.
This system variable always contains the value zero for the following operating or TP monitor systems on mainframe computers:
CICS
IMS TM
Format/length: | A32 |
Content modifiable: | No |
This system variable contains the name of the currently executed unit. This is
the function name in case of the object type "function",
the inline subroutine name if an inline subroutine is performed,
the external subroutine name in case of the object type
"subroutine", see also *SUBROUTINE
,
the object name in case of all other object types (program,
subprogram, map, dialog, etc.); see also *PROGRAM
.
The contents of *CURRENT-UNIT
will
always be in upper case.
Format/length: | N3 |
Content modifiable: | No |
This system variable contains the number of data elements in the
Natural stack which are available to the next INPUT
statement as input data.
*DATA
will contain 0
when the stack
is empty. A value of -1
indicates the next element in the stack is
a command or the name of a Natural transaction.
The settings of the Natural profile/session parameters
IA
(Input
Assign Character) and ID
(Input Delimiter
Character) at the time of execution of the STACK
statement are used to
determine the *DATA
value.
Format/length: | L |
Content modifiable: | No |
This system variable indicates whether the Natural program, data area, and map editors are enabled and can be used.
It can contain one of the following values:
Value | Description |
---|---|
TRUE | The editors are enabled. |
FALSE | The editors are not enabled and cannot be used. |
For information on NaturalONE as the Default Development Environment, see the relevant section in the Editors documentation.
Note:
The editors are also enabled if Natural ISPF is
installed.
Format/length: | N4 |
Content modifiable: | No |
This system variable contains the source-code line number of the statement that caused an error.
*ERROR-LINE
is reset to 0
when a Level 1 program starts executing.
Alternatively, you may specify
*ERROR
.
Format/length: | N7 |
Content modifiable: | Yes |
This system variable contains the error number of the error which
caused an ON ERROR
condition to be entered.
Only error numbers in the range from 0 to 9999 are supported.
Normally, *ERROR-NR
contains the
Natural system error number which caused an error condition to be
entered; however, when a REINPUT WITH TEXT
*nnnn
statement is executed, the
application-specific message number nnnn is
placed into *ERROR-NR
.
You may modify the content of this system variable via a Natural
program; however, not within an ON
ERROR
statement block.
*ERROR-NR
is reset to 0
when a Level 1 program starts executing.
Format/length: | A8 |
Content modifiable: | Yes |
This system variable contains the name of the error transaction program which is to receive control in the event of an error condition.
For further information, see Using an Error Transaction Program in the Programming Guide.
Format/length: | A8 |
Content modifiable: | No |
This system variable contains the current identifier of transaction data for Adabas. The default value is one of the following:
the value of the Natural profile parameter
ETID
,
the user ID as passed from the TP monitor,
the value provided in the user exit during Natural initialization,
the value from the security profile of the currently active user (applies only under Natural Security).
Format/length: | P10 |
Content modifiable: | Yes |
This system variable contains the Adabas internal sequence number
(ISN) of the record currently being processed within a processing loop
initiated by a FIND
or
READ
statement.
(r)
notation after *ISN
is used to indicate
the label or statement number of the statement in which the FIND
or READ
was issued. If (r)
is not specified, *ISN
represents the ISN of the
record currently being processed in the currently active processing loop.
For the HISTOGRAM
statement,
*ISN
contains the number of the occurrence in
which the descriptor value last read is contained
(*ISN
= 0 if the descriptor is not contained
within a periodic group).
Format/length: | I4 |
Content modifiable: | No |
*LBOUND
contains the current lower
boundary (index value) of an array for the specified dimension(s) (1, 2 or 3)
or for all dimensions (asterisk (*) notation).
Syntax:
*LBOUND
(operand1 [,dim])
|
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand1 | A | A | U | N | P | I | F | B | D | T | L | C | G | O | yes | no |
operand1 is the array for which the lower boundary is specified. The index notation of the array is optional. As index notation only the complete range notation * is allowed for each dimension.
dim is the dimension number for which the current lower boundary is returned:
dim = |
1 |
If no dimension is specified, the lower bound of the first dimension is returned.
If 1, 2 or 3 is specified, the lower bound of the first, second or third dimension is returned.
If * is specified, the lower bound of all the defined dimensions are returned, that is,
1 in case of an one dimensional array,
2 in case of a two dimensional array,
3 in case of three dimensional array.
If an X-array is not allocated and the lower bound of the specified
dimension of this X-array is the variable index bound, that is, it is
represented by an asterisk (*) character in the index definition, the lower
bound of the specified dimension is undefined, and access to
*LBOUND
leads to a runtime error. In order to
avoid the runtime error, *OCCURRENCE
may
be used to check against zero occurrences:
DEFINE DATA LOCAL 1 #XA(A5/1:*) END-DEFINE IF *OCCURRENCE (#XA) NE 0 AND *LBOUND(#XA) > 10 THEN ...
Examples:
DEFINE DATA LOCAL 1 #I (I4) 1 #J (I4/1:3) 1 #XA (A5/10:*,20:*) END-DEFINE #I := *LBOUND(#XA) /* lower bound of 1st dimension is 10 #I := *LBOUND(#XA,1) /* lower bound of 1st dimension is 10 #I := *LBOUND(#XA,2) /* lower bound of 2nd dimension is 20 #J(1:2):= *LBOUND(#XA,*) /* lower bound of all dimensions /* #J(1) is 10 and #J(2) is 20 END
See also *UBOUND
and
*OCCURRENCE
.
Format/length: | I4 |
Content modifiable: | No |
This system variable returns the currently used length of a field
defined as dynamic variable in terms of code units; for A and B format the size
of one code unit is 1 byte and for U format the size of one code unit is 2
bytes (UTF-16).
*LENGTH(field)
applies
to dynamic variables only.
See also Value Space Currently Used for a Dynamic Variable in the Programming Guide.
Format/length: | N2 |
Content modifiable: | No |
This system variable contains the level number of the program,
subprogram, external subroutine, map, helproutine or dialog which is currently
active. Level 1 is a main program. If higher levels occur during runtime
(maximum = 1024
), then the content of
*LEVEL
will be 99
.
*LEVEL
does not apply to inline
subroutines.
See also Using an Error Transaction Program in the Programming Guide.
Format/length: | A8 |
Content modifiable: | No |
This system variable contains the current library ID (as specified
by the user in the LOGON
command).
This variable is the equivalent of the variable
*APPLIC-ID
.
Format/length: | I4 |
Content modifiable: | No |
It contains the number of the line currently executed in a Natural object.
If a Natural object has been compiled with the
Natural Optimizer
Compiler, the value of *LINE
may not
reflect the correct line number if the source line where the system variable is
used is part of a sequence of statements that have been optimized by the
Natural Optimizer Compiler.
Format/length: | A100 |
Content modifiable: | No |
Returns the line number of the statement currently executing, with
all line numbers of used INCLUDE
levels.
When used in the main source of a program (not inside a copycode),
it returns only the number of the line in which it is referenced. In this case,
the data is the same as what is returned by *LINE
, except the
format is (A100).
If *LINEX
is used in a (nested)
INCLUDE
structure, all the line numbers starting from the first
INCLUDE
up to the last INCLUDE
and the line number of
the statement are returned in this field, separated from each other by a
slash.
Example:
.... 3200 3210 INCLUDE COPY01 0010 ... 0020 ... .... 0200 INCLUDE COPY02 0010 ... 0020 ... .... 0050 PRINT *LINEX
The output produced by the PRINT
statement is
3210/0200/0050
and represents the complete line number path needed
to exactly locate the position where *LINEX
was
referenced initially.
Format/length: | A8 |
Content modifiable: | No |
This system variable contains the library ID from where the current executed object was loaded.
Format/length: | P10 |
Content modifiable: | Yes |
This system variable contains either of the following:
the number of records which were selected as a result of a
FIND
statement (as a
result of the WITH
clause);
the number of values selected as a result of a
HISTOGRAM
statement;
the end offset of the fetched segment as a result of a
READLOB
statement;
the end offset of the inserted segment as a result of an
UPDATELOB
statement.
(r)
notation after *NUMBER
is used to
indicate the statement label or source-code line number of the associated
statement. If (r)
is not specified,
*NUMBER
automatically refers to the innermost
active FIND
,
HISTOGRAM
or READLOB
processing loop by
default. The (r) notation is always required, if
*NUMBER
refers to an UPDATELOB
statement.
Note:
When *NUMBER
is used in conjunction
with a FIND
statement and the Adabas file accessed is protected by
the Adabas facility Security By Value, *NUMBER
will contain 9999999999
, if more than 1 record was found. If 1
record was found, *NUMBER
will contain 1. If no
record was found, *NUMBER
will contain 0.
VSAM | For VSAM databases,
*NUMBER only contains the number of records found
when used with a HISTOGRAM statement, or with a
FIND statement which uses the operator EQUAL TO in
the search criterion. With any other operator,
*NUMBER will not contain the number of records
found: *NUMBER will be 0 if no
records have been found; any other value indicates that records have been
found, but the value will have no relation to the number of records actually
found.
|
---|---|
SQL Databases | For SQL databases,
*NUMBER only contains the number of rows found,
when used with a FIND
NUMBER or with a HISTOGRAM statement without a
WHERE clause. In all other cases,
*NUMBER will not contain the number of rows found:
*NUMBER will be 0 if no rows have
been found; any value other than 0 indicates that rows have been
found, but the value will have no relation to the number of rows actually
found.
|
Format/length: | I4 |
Content modifiable: | No |
This system variable provides the current number of occurrences of an array. It can be applied to all kinds of array fields, with a fixed or variable number of occurrences.
This covers:
static arrays with a constant number of occurrences
Example: (1:5)
X-Arrays with an alterable number of occurrences
Example: (1:*)
parameter arrays, defined as (1:V)
Syntax:
*OCCURRENCE
(operand1 [,dim])
|
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand1 | A | A | U | N | P | I | F | B | D | T | L | C | G | O | yes | no |
operand1 is the array for which the
number of occurrences is returned. The index notation of the array is optional.
If supplied, only the complete range notation * is allowed for each dimension,
such as *OCC(#X(*))
or *OCC(#Y(*,*))
.
dim is the dimension number for which the current number of occurrences is returned:
dim = |
1 |
Explanation:
1 |
One-dimensional array. This is the default, if dim is not specified. |
2 |
Two-dimensional array. |
3 |
Three-dimensional array. |
* |
All dimensions defined for the corresponding array apply. |
In a parameter data area, you can use the index notation
(1:V)
to define an array with a variable number of occurrences
(see the DEFINE DATA
statement). The current number of occurrences of such an array is determined at
runtime. With *OCCURRENCE
, you can ascertain the
current number of array occurrences.
Examples:
DEFINE DATA PARAMETER 1 #PARR (I2/1:V) LOCAL 1 #FARR (I2/1:5) 1 #XARR1 (I2/1:*) 1 #XARR2 (I2/1:*,1:*) 1 #I (I2) 1 #J (I2) END-DEFINE FOR #I = 1 TO *OCC(#PARR) /* Parameter array WRITE 2X #I END-FOR FOR #I = 1 TO *OCC(#FARR) /* Fixed array WRITE 4X #I END-FOR EXPAND ARRAY #XARR1 TO (1:4) FOR #I = 1 TO *OCC(#XARR1) /* X-Array WRITE 6X #I END-FOR EXPAND ARRAY #XARR2 TO (1:3,1:4) FOR #I = 1 TO *OCC(#XARR2,1) /* X-Array FOR #J = 1 TO *OCC(#XARR2,2) WRITE 8X #I #J END-FOR END-FOR END
See also the example programs
OCC1P
and
OCC2P
.
Concerning X-arrays, *OCCURRENCE
contains the current number of occurrences:
DEFINE DATA LOCAL 1 #I (I4) 1 #J (I4/1:3) 1 #XA (A5/1:*,1:*) END-DEFINE EXPAND ARRAY #XA TO (1:10,1:20) #I := *OCC(#XA) /* #I=10 #I := *OCC(#XA,1) /* #I=10 #I := *OCC(#XA,2) /* #I=20 #J(1:2) := *OCC(#XA,*) /* #J(1)=10 #J(2)=20 END
Format/length: | U(dynamic) |
Content modifiable: | No |
This system variable contains the name of the current event delivered from Natural for Ajax.
It is used for rich GUI programming with the
PROCESS
PAGE
statement. For further information, see the
Natural for Ajax documentation.
Format/length: | I4 |
Content modifiable: | No |
This system variable contains the level of the active
PROCESS PAGE
MODAL
statement blocks.
If no
PROCESS PAGE
MODAL
is active, the value of
*PAGE-LEVEL
is 0
.
Note:
If the value of *PAGE-LEVEL
is
greater than 0
, no output to Report 0 via an INPUT
,
PRINT
, WRITE
or DISPLAY
statement is
possible.
Format/length: | A8 |
Content modifiable: | No |
This system variable contains the name of the Natural object that is currently being executed.
Format/length: | A16 |
Content modifiable: | No |
This system variable indicates whether the application is in a state
that allows execution of a REINPUT
or
PROCESS PAGE
UPDATE
statement.
An application can use an INPUT
and (if running with
Natural for Ajax) a
PROCESS PAGE
USING
statement to perform an input/output processing. Under
certain conditions, an application may return and re-execute these I/O
statements with a REINPUT
or PROCESS PAGE UPDATE
statement.
The value returned by this system variable indicates whether or not such a re-executing statement is possible at this position. It returns one of the following values:
Value | Description |
---|---|
(blanks) | The application can neither perform a
REINPUT nor a PROCESS PAGE UPDATE statement.
|
REINPUT |
The application can perform a
REINPUT , but no PROCESS PAGE UPDATE
statement.
|
UPDATE |
The application can perform a
PROCESS PAGE UPDATE , but no REINPUT
statement.
|
Format/length: | I4 |
Content modifiable: | No |
This system variable contains the number of rows that were deleted,
updated or inserted by one of the Natural SQL statements
"searched"
DELETE
,
"searched"
UPDATE
or INSERT
(with
select-expression),
respectively. *ROWCOUNT
always refers to the last
executed one of these statements.
Format/length: | A8 |
Content modifiable: | Yes |
The program whose name is contained in this system variable will be
executed whenever Natural would otherwise display the command input prompt
(NEXT
prompt or direct command line/window).
- Initial Setting without Natural Security
If Natural Security is not used, the value of
*STARTUP
depends on the setting of the profile parameterMENU
:
If
MENU=OFF
is set,*STARTUP
is blank.If
MENU=ON
is set,*STARTUP
containsMAINMENU
; that is, the Natural main menu will be displayed.- Initial Setting with Natural Security
If Natural Security is used and a logon to a library is executed,
*STARTUP
contains the name of the program which has been entered in Natural Security as the startup transaction in the security profile of the respective library (except in batch mode; see also the Natural Security documentation).- Setting at Runtime
You can assign a program name to
*STARTUP
which always overwrites the content of*STARTUP
.
Perform the following steps to deactivate the program contained in
*STARTUP
:
Depending on the context in which
*STARTUP
is used, there are several ways to
properly terminate a startup program without causing a program loop or Natural
error NAT9969, respectively. Choose one of the following options:
Set the *STARTUP
system
variable to a blank value (for example, by using the RESET
*STARTUP
statement) and finish the startup afterwards.
Terminate the session.
Force a logoff or a logon to another library.
If the *STARTUP
program issues a
MORE
prompt, enter a command or another input to interrupt the
program.
If the *STARTUP
program issues any output,
request a command prompt by issuing a Natural %%
terminal command.
A %%
command deactivates the startup program in either a non-security or Natural
Security environment in which command mode is allowed for the current
library.
When you define a startup program, consider that values returned
for the system variables *DEVICE
,
*SERVER-TYPE
or
*SCREEN-IO
can
affect the program result. For example, perform the following steps to avoid
undesirable results:
In batch mode (*DEVICE
or
*SCREEN-IO
),
include a FETCH
or STACK
COMMAND
statement in the startup program; otherwise, a
program loop or Natural error NAT9969 can occur.
If you map a Natural Development Server environment (*SERVER-TYPE
)
from NaturalONE and select a library with an active
*STARTUP
, make sure that the startup program does
not perform screen I/O and terminates properly in the respective library (a
logon to another library is not allowed). You can use the application
programming interface USR4218N to find out whether NaturalONE is your current
system environment. See also the description of startup transactions in the
section Using an Existing Natural Development Server
Environment, the section Frequently Asked
Questions and the Glossary in the
NaturalONE documentation.
- *STARTUP under Natural Security
In a Natural Security environment in which command mode is prohibited for the current library,
%%
will cause the program whose name is contained in*STARTUP
to be invoked.The startup program must contain a
FETCH
orSTACK COMMAND
statement if the NEXT/MORE line is not allowed in the security profile of the library where the program resides. See also the corresponding option setting described in Security Options in the section Library Maintenance in the Natural Security documentation.When a Natural runtime error occurs which is caused by a startup transaction (
*STARTUP
), Natural's error processing might lead to the startup transaction being executed again. This would cause an error-loop situation. To prevent such a loop, the general option Logoff in error case if *STARTUP is active is available. See Logoff in Error Case if *STARTUP is Active in the Natural Security documentation.
Format/length: | A8 |
Content modifiable: | No |
This system variable contains the name of the steplib library which has been concatenated to the Natural library to which the user is currently logged on.
If Natural Security is not active,
*STEPLIB
contains the name specified with the
profile parameter STEPLIB
.
If Natural Security is active, the value may be defined in the security profile of a given library.
Note:
The database ID and file number of the
*STEPLIB
library are derived from its name. Apart
from the library SYSTEM
, libraries with the name
SYSxxx
are assumed to be in
FNAT
and other libraries are assumed to be in
FUSER
.
Format/length: | A32 |
Content modifiable: | No |
This system variable contains the name of the external subroutine
that is currently being executed. The contents of
*SUBROUTINE
will always be in upper case.
Format/length: | HANDLE OF OBJECT |
Content modifiable: | No |
This system variable contains a handle to the currently active
object. The currently active object uses
*THIS-OBJECT
to either execute its own methods or
pass a reference to itself to another object.
*THIS-OBJECT
only contains an actual
value when a method is being executed. Otherwise it contains
NULL-HANDLE
.
Format/length: | A32 |
Content modifiable: | No |
This system variable contains the type of the Natural object which is currently executed.
Valid values of *TYPE
:
Value | Object Type |
---|---|
PROGRAM |
Program |
FUNCTION |
Function |
SUBPROGRAM |
Subprogram |
SUBROUTINE |
Subroutine |
HELPROUTINE |
Helproutine |
MAP |
Map |
ADAPTER |
Adapter |
Format/length: | I4 |
Content modifiable: | No |
*UBOUND
contains the current upper
boundary (index value) of an array for the specified dimension(s) (1, 2 or 3)
or for all dimensions (* notation).
Syntax:
*UBOUND
(operand1 [,dim])
|
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand1 | A | A | U | N | P | I | F | B | D | T | L | C | G | O | yes | no |
operand1 is the array for which the upper boundary is specified. The index notation of the array is optional. As index notation only the complete range notation * is allowed for each dimension.
dim is the dimension number for which the current upper boundary is returned:
dim = |
1 |
If no dimension is specified, the upper bound of the first dimension is returned.
If 1, 2 or 3 is specified, the upper bound of the first, second or third dimension is returned.
If * is specified, the upper bound of all the defined dimensions are returned, that is
1 in case of an one dimensional array,
2 in case of a two dimensional array,
3 in case of three dimensional array.
If an X-array is not allocated and the upper bound of the specified
dimension of this X-array is the variable index bound, that is, it is
represented by an asterisk (*) character in the index definition, the upper
bound of the specified dimension is undefined, and access to
*UBOUND
leads to a runtime error. In order to
avoid the runtime error, *OCCURRENCE
may
be used to check against zero occurrences:
DEFINE DATA LOCAL 1 #XA(A5/1:*) END-DEFINE IF *OCCURRENCE (#XA) NE 0 AND *UBOUND(#XA) > 10 THEN ...
Examples:
DEFINE DATA LOCAL 1 #I (I4) 1 #J (I4/1:3) 1 #XA (A5/*:10,*:20) END-DEFINE #i := *UBOUND(#XA) /* upper bound of 1st dimension is 10 #i := *UBOUND(#XA,1) /* upper bound of 1st dimension is 10 #i := *UBOUND(#XA,2) /* upper bound of 2nd dimension is 20 #j(1:2):= *UBOUND(#XA,*) /* upper bound of all dimensions /* (1st and 2nd) /* #J(1) is 10 and #J(2) is 20
See also *LBOUND
and
*OCCURRENCE
.