Chapter 10:  System Functions

System functions can perform many common, time-consuming tasks.  Such tasks would otherwise have to be done through Interactive Commands Language (ICL) or the Structured Programming Language (SPL).  System functions operate by converting or calculating one value from another.  They perform tasks such as calculating square roots, rounding numbers, and truncating values.  Several logarithmic functions are provided.  System functions also allow access to such information as the number of milliseconds of CPU time used, the lowest and highest value found in a group of numbers or dates, and the destination of a report.  Many of the system functions also perform format conversions on dates, strings, and numbers.

The values entered with system functions are called arguments.  An argument can consist of one or more variables, constants, literal expressions, or other functions.  The number of arguments varies with the function.  Some arguments are required and others are optional.

The form and data type of the arguments must be appropriate to the function being used.  It is often advisable to test the input values, to be sure they are appropriate, before using them with a function.  The relational operators, described in Chapter 9, are used for this purpose.  The input arguments are themselves unchanged by the function.

The value returned by a system function is available for processing by a command, a statement, or another function.  The function can be used wherever the returned data type is appropriate.

This chapter contains a quick reference table of all functions, showing the data type of their primary argument and result, and the tasks they perform.  The table is followed by an alphabetic list of functions, which gives a detailed discussion of what they do and shows the arguments appropriate to each.  The universal date and time functions are discussed at the end of this chapter.

Conventions for Functions

A system function must be entered exactly as shown in the General Form, with no abbreviations.  The input data types must be as specified.  See Chapter 4 for a discussion of data types.  The number of arguments must be exactly as specified, unless an argument is optional (indicated with square brackets []).

The following rules for delimiters apply to all system functions:

• When the function has more than one argument, the arguments are separated by commas and are enclosed in parentheses.

• When a single argument is an expression, including a constant with a unary negative sign, the argument must be enclosed in parentheses.

• When a single argument consists of a single value, parentheses are optional.

Quotation marks are needed on all string literals, but not on numeric literals unless they are to be accepted as strings.

Table 10-1 Definitions of Arguments Used in Functions

Locator Index to Functions

Table 10-3 will help locate the right function to do a particular task.  The meaning of the column headings is as follows:

Click here to view Table 10-2 Heading Definitions.

Descriptions Of Functions

@ABS ae

Returns absolute value (magnitude) of the same data type as the argument.  Example:

*TYPE @ABS (-5.79/3)

1.93

@ACOS ae

Returns the degrees angle of a cosine argument.  Example:

*TYPE @ACOS .9

25.841933

@ACOSR ae

Returns the radians angle of a cosine argument.  Example:

*TYPE @ACOSR .9

.45102681

@ADR field

Returns an integer value, which represents the address in memory of the specified field (scalar, vector, or array instance).  Although @ADR resembles a system function, it works as an operator.

NOTE:  This system function is intended to be used only by routines which require a "by reference" (as opposed to a "by value") argument for reading or writing data. It may be used with System Fields, Global Storage fields, declared fields in a Process Module (PM), and any fields in a Data Set.  Parentheses are not allowed on the field.  @ADR cannot be used interactively.

The called routine should not go beyond the bounds of ACCENT R's data management.  It cannot be used in normal statements for data replacement (<ae> to @ADR is not valid).  However, @ADR field may be a valid argument for an external routine.

Example:  (line from PM initial section):

*LIST PM CALL_EDT

DECLARE SECTION

FILENAME,CHA,200,DATA X.X

GROUP DSC.LIST OCCURS 1 TIMES

W_LENGTH, BB, 16

B_TYPE, BB, 8

B_CLASS, BB, 8

A_POINTER,I,max

GROUP END

INITIAL SECTION

@LEN(FILENAME:D) TO W_LENGTH:D(1)

14 TO B_TYPE:D(1)

1 TO B_CLASS:D(1)

@ADR FILENAME:D TO A_POINTER:D(1)

@CALL(EDT$EDIT ,EDTSHR ,@ADR W_LENGTH(1)) TO @INTEGER.

@ASC str

Returns the integer ASCII code that represents the first character of the string argument.  Example:

*TYPE @ASC "YES"

89

@ASIN ae

Returns the degrees angle of a sine argument.  Example:

*TYPE @ASIN .9

64.158067

@ASINR ae

Returns the radians angle of a sine argument.  Example:

*TYPE @ASINR .9

1.1197695

@ATAN ae

Returns the degrees angle of a tangent argument.  Example:

*TYPE @ATAN .9

41.987212

@ATANR ae

Returns the radians angle of a tangent argument.   Example:

*TYPE @ATANR .9

.7328151

@BREAK (str1,str2)

Returns the portion of str1 that precedes the first occurrence of any character in str2. The break character is stored in @TOKEN.  If none of the characters in str2 are found in str1, str1 is returned and @TOKEN contains a null. If str2 is null, the value of @BREAK is null and @TOKEN contains a null. @BREAK can handle lower case strings under the control of the ENABLE/DISABLE SEQUENCE LOWER option.  Exact case match is no longer needed for strings when SEQUENCE LOWER is disabled.  In appropriate cases, the @TOKEN value is returned as it appears in its source string.  Its case will not be altered even though it may have matched a different case item.

See @EXTRACT or @SPAN for the other portion of str1.  If str2 is a field name, and if one of the field values contains a space, the space should not be the final character, since it might be truncated, particularly if FIELDTRIM is enabled.

@BREAK("AB,CD/EF",",/")returns "AB" @TOKEN& =
@BREAK("AB/CD,EF",",/")returns "AB" @TOKEN& = "/"
@BREAK("SALES:4500",":")returns "SALES" and @TOKEN = ":"

@CAL str

Returns a date value equivalent to the string argument.  Only input strings that are valid dates cause a date to be returned.  Others cause the value of the system field @NODATE to be returned.  The relational operator CALENDRICAL can be used to test str before @CAL is applied.  Use this function to convert strings to dates for comparison with date fields.  Example:

*EXTRACT IF INV.DATE GT @CAL "910930"

@CALL

The @CALL System Function is useful for integrating with existing applications which rely on subroutine libraries in order to perform calculations and field edits, calling special purpose libraries such as graphics and statistical function libraries, and calling OpenVMS run-time library routines.  See the section at the end of this chapter for a detailed description of external subroutines.

@CENTER (str,int)

Returns the first argument str centered in the number of characters specified by the second argument int.  Leading and trailing spaces are added as required.  If str is longer than the length specified, leading and trailing characters are removed as required.  Example:

*TYPE "#",@CENTER ("TITLE",9),"#"

 # TITLE #

@CHECK_EXPRESSION

This system function checks the syntax of arithmetic expressions, date expressions, and relational arithmetic expressions.  It returns a string status indicator value of YES or NO, reflecting the validity of a syntax check of the string argument.  If the status is NO, indicating an invalid expression, the System Field @TOKEN_POS will contain the position within the string at which the error was detected.  If the status is YES, @TOKEN_POS stays at zero. Example:

*TYPE @CHECK_EXPRESSION ("@NUMBER +")

NO

*TYPE @TOKEN_POS

9

*TYPE @CHECK_EXPRESSION ("@NUMBER + 1")

YES

*TYPE @TOKEN_POS

0

NOTE:  The string argument may start with any valid data operand such as a literal, constants, Data Set names, System Field names, and unary operators or functions (such as "-", "+", or system functions).  The string argument can also contain IF, UNLESS, ORIF, or ORUNLESS followed by valid relational expression syntax.

@CHECK_EXPRESSION is an expression syntax check, not a semantic check, thus operand data type errors are not detected by @CHECK_EXPRESSION.

@CHR ae

Returns the ASCII character whose decimal code is represented by the argument.  This function can be used to generate special characters that are not available directly, like control characters.  See Appendix D for a list of ASCII characters and their decimal codes.  Example:

*TYPE @CHR 89,@CHR 69,@CHR 83

YES

@COMMAND_TEXT

Returns the text of a command line used to invoke an equated command.  The text will be an exact line image and will include the command name.  To use the text, the equated Process Module (PM) or Command Module (CM) must contain code to properly parse it.  @COMMAND_TEXT will return a null string after a USE PM or USE CM has been executed, unless a PRESERVE TEXT clause is included in the definition of the equated command.  Other ACCENT R commands do not affect the results of this function.

The maximum length of the string returned by @COMMAND_TEXT is limited by the system field @TERM_LINE, which has a default width of 525 characters and can be changed to any value between 25 to 4095.  Changing @TERM_LINE will cause @COMMAND_TEXT to return a null string.

@COMMAND_TEXT is terminated by both a carriage return and a line feed.

@COS ae

Returns the cosine of the argument expressed in degrees.  Example:

*TYPE @COS .9

.99987663

@COSR ae

Returns the cosine of the argument expressed in radians. Example:

*TYPE @COSR .9

.62160997

@COUNT (str1, str2 [ ,ae])

Returns the number of non-overlapping occurrences of str2 within str1, beginning at position ae in str1.  ACCENT R assumes the value of ae to be 1 if ae is zero, negative, or omitted.  If there are fewer characters to the right of position ae in str1 than specified in str2, a zero is returned.  A numeric value for ae is rounded to an integer before calculation.

@COUNT can handle lower case strings under the control of the ENABLE/DISABLE SEQUENCE LOWER option.  Exact case match is not needed for strings when SEQUENCE LOWER is disabled.

The first example counts the occurrences of JONES .  The second counts the number of spaces.

*TYPE @COUNT ("BOB JONES, TOM Jones, &

ED MOORE, TIM BRECORDN, JOHN JONES, STEVE &

MARLOW", "JONES")

3

*TYPE @COUNT ("BOB JONES, TOM JONES, &

ED MOORE, TIM BRECORDN, JOHN JONES, &

STEVE MARLOW"," ")

10

@DATE_DIFF (dae1, dae2)

Finds the difference between two extended date and time values.  The output is a numeric value of days and fractions thereof.

*TYPE @DATE_DIFF (@DTVAL("6-MAY-1993 12:00"),

@DTVAL("4-MAY-1993 6:00"))

2.25

@DATE_DIFF_STR ae

Given the numeric difference between two dates (as would be returned by the @DATE_DIFF function), this function produces a string of form:

"dd hh:mm:ss"

where:dd - represents days (0. . .N)

hh - represents hours per: 0<=hh<24

mm - represents minutes per: 0<=mm<60

ss - represents seconds per: 0<=ss<60

@DATSTR (date [,str])

Converts an input date value to a string value per the image described by str, where str contains date formatting characters as described in the following table.  Any other characters in str are copied literally to the resultant string.  If string is omitted, the default value is MM/DD/YYYY (optionally YYYY-MM-DD or DD/MM/YYYY if ENABLE (ISO;EUR) DATE is in effect).

Formatting characters can be in upper or lower case.  There must be one format character for each position.  An entry of 9M is not allowed; MMMMMMMMM must be entered.

@DEFINE_LOGICAL ("logical_name", "definition_string")

This function defines a logical name to be the specified string.  You can create a data set with a logical name and at runtime define its location.  Example:

CREATE DS SALES: SD SALES.REC ENTRY ONLY

SET @DEFINE_LOGICAL("SALES",'NY:[NYC]SALES')TO @STRING

USE DS SALES:

This function return "YES" if successful and "FAIL" if unsuccessful.

@DEGREES ae

Returns the degrees of a radian argument.  Example:

*TYPE @DEGREES .9

51.566202

@DMAX (\\date\\)

Returns the date value that is the latest (highest) of the arguments given.  In the following example, @DMAX is used to find the latest of three dates stored in GS fields:

*TYPE %DAT1,2B,%DAT2,2B,%DAT3

05/17/91 12/01/90 07/19/91

*TYPE @DMAX (%DAT1,%DAT2,%DAT3)

 07/19/1991

@DMIN (\\date\\)

Returns the date value that is the earliest (lowest) of the arguments given.  This example is related to the one above.

*TYPE @DMIN (%DAT1,%DAT2,%DAT3) 05/17/1991

@DTSTR (date expression [,"format_string"])

@DTSTR converts an enhanced FULLDATE data type field (date and time) value into a formatted string.  @DTVAL ("string") or @DATETIME may be used for the date expression.  Example:

*TYPE @DTSTR (@DTVAL("28-AUG-1991 12:34:56.789"))

08/28/1991 12:34:56.788

@DTVAL ('string')

@DTVAL converts formatted strings into enhanced FULLDATE data type date and time values.  The string format is:  dd-mmm-yyyy:HH:MM:SS.ccc .  (Example:  "28-AUG-1991 12:34:56.789").  Time currently does not display.  Example:

*TYPE @DTVAL "28-AUG-1991 12:34:56.789"

08/28/1991

@DVAL str

Returns a date value equivalent to the string argument.  @DVAL is identical to @CAL.  The following example converts a string to a date value so that it can be stored in a GS field of data type F:

*SET @DVAL 7/25/91 TO %DAT4

*TYPE %DATE

07/25/1991

@E

Base of natural logarithm; E = 2.718 281 828 459 045 24.  Numerical accuracy depends on hardware or software double precision. Example:

*TYPE @E

2.7182818

*TYPE@ 'Z.17Z'

2.71828182845904526

@EDIT str

This System Function takes a single string argument containing the name of a file to be created or edited.  The return value of @EDIT is also a string with the value of "YES" if the editor invocation succeeded or the value "ERROR" if the editor invocation failed.

@ENABLE_STATUS  (option)

This system function returns the setting of a specified ENABLE/DISABLE option. The character string returned has one of these values:

1. ENABLE means the option is enabled.
2. DISABLE means the option is disabled.
3. UNKNOWN means the option is not a valid ENABLE/DISABLE option.

The option is a string expression that is evaluated to be an ENABLE/DISABLE option name.  Example:

ENABLE ISO DATE IF @ENABLE_STATUS (‘ISO DATE’) NE ‘ENABLE’

This command enables the ISO date if it is not already enabled.

@EVENT_CLEAR (key , event)

Clears an event flag in cluster 2. A status code is returned with possible values of:

1. -1 (failure, bad argument(s) or resources exhausted);
2. 0 (success, event flag was previously clear);
3. +1 (success, event flag was previously set).

NOTE:  Key is the name associated with the cluster event.  Event is the event flag number (1-32).  The SYS$CLREF system call is used internally to implement this function.  See notes on Current Processing at the end of the chapter.  Example:

*TYPE @EVENT_CLEAR (TEST ,13)

0

@EVENT_READ (key , event)

Reads the present setting of an event flag in cluster 2.  A status code is returned with possible values of:

1.  -1 (failure, bad argument(s) or resources exhausted);
2.  0 (success, event flag is clear);
3.  +1 (success, event flag is set).

NOTES:  Key is the name associated with the cluster event.  Event is the event flag number (1-32).  The SYS$READEF system call is used internally to implement this function.  See notes on Current Processing at the end of the chapter.  Example:

*TYPE @EVENT_READ(TEST ,15)

1

@EVENT_SET ("key", event)

Sets an event flag in cluster 2.  A status code is returned with possible values of:

1. -1 (failure, bad argument(s) or resources exhausted);
2. 0 (success, event flag was previously clear);
3. +1 (success, event flag was previously set).

After the event flag is set, processes that were waiting for the event flag to be set will resume execution.

NOTES: "Key" is the name associated with the cluster event.  "Event" is the event flag number (1-32).  The SYS$SETEF system call is used internally to implement this function.  See notes on Current Processing at the end of the chapter.  Example:

*TYPE @EVENT_SET  ("TEST", 9)

1

@EVENT_WAIT ("key", event)

A wait (process hibernation) until the specified event flag in cluster 2 is set.  A status code is returned with possible values of:

1.  -1 (failure, bad argument(s) or resources exhausted);
2.  +1 (success, event flag has been set by another process).

If the specified event flag is already set, the calling process will not hibernate and the function will return immediately.  For this reason, it is generally advised that an event flag be cleared by the activated process.  The decision to clear event flags is application dependent.  See notes on Current Processing at the end of the chapter.

NOTES:  "Key" is the name associated with the cluster event.  "Event" is the event flag number (1-32).  The SYS$WAITFR system call is used internally to implement this function.  See notes on Current Processing at the end of the chapter.  Example:

*TYPE @WAIT  ("TEST", 9)

 1

@EVENT_WAIT_ALL ("key", event [,...,event.n])

Waits (process hibernation) until all the specified event flags in cluster 2 are set.  The event flags may be listed in any order.  A status code is returned with possible values of:

1. -1 (failure, bad argument(s) or resources exhausted);
2. n (success, lowest event flag number to be set).

If the specified event flag is already set, the calling process will not hibernate and the function will return immediately.  For this reason, it is generally advised that an event flag be cleared by the activated process.  The decision to clear event flags is application dependent.

NOTES:  "Key" is the name associated with the cluster event.  "Event" is the event flag number (1-32).  The event numbers are placed in a bitmap through an "exclusive or" (XOR - logical operator) for use by the SYS$WFLAND system call.  See notes on Current Processing at the end of the chapter.  Example:

*TYPE @EVENT_WAIT_ALL  ("TEST", 7, 9, 11)

7

@EVENT_WAIT_ANY ("key", event [,...,event.n])

Waits (process hibernation) until any one of the specified event flags in cluster 2 are set.  The event flags may be listed in any order.  A status code is returned with possible values of:

1.  -1 (failure, bad argument(s) or resources exhausted);
2.  n (success, lowest event flag number that was set ).

If the specified event flag is already set, the calling process will not hibernate and the function will return immediately.  For this reason, it is generally advised that an event flag be cleared by the activated process.  The decision to clear event flags is application dependent.

NOTES:  "Key" is the name associated with the cluster event.  "Event" is the event flag number (1-32).  The event numbers are placed in a bitmap through an "exclusive or" (XOR - logical operator) for use by the SYS$WFLAND system call. See notes on Concurrent Processing at the end of the chapter.  Example:

*TYPE @EVENT_WAIT_ANY  ("TEST", 5, 10, 15)

10

@EXP ae

E raised to the power ae. Example:

*TYPE @EXP 5

148.41316

@EXTRACT (str1,str2) [,int[,ignore_str]])

Returns the portion of str1 that precedes the first occurrence of any character in str2.  If int is included, the search of str1 begins at the character position of int.  If ignore_str is included, the search skips any leading characters that match any of those in ignore_str.  The break character from str2 is stored in @TOKEN, which should be tested to determine whether @EXTRACT succeeded or failed.  The index of the break character within the original str1 is stored in @TOKEN_POS.  If none of the characters in str2 is found in str1, the value of str1 modified by index and ignore_str is returned, @TOKEN contains a null, and @TOKEN_POS contains the position of the end of str1.  If str2 is null, the value of @EXTRACT is null, @TOKEN contains a null, and @TOKEN_POS is zero

@EXTRACT can handle lower case strings under the control of the ENABLE/ DISABLE SEQUENCE LOWER option.  Exact case match is not needed for strings when SEQUENCE LOWER is disabled.  In appropriate cases, the @TOKEN value is returned as it appears in its source string.  Its case will not be altered although it may have matched a different case item.

The facility of having a starting index and an ignore string allows scanning a string without having to strip the currently processed token from the string each time, thus replacing the need for @BREAK and @SPAN in most cases.  If str2 is a field name, and if one of the values in the field is a space, the space should not be the final character in the field, since it might be truncated, particularly if FIELDTRIM is enabled.  Example:

*TYPE @EXTRACT("AB,CD/EF",",/")

"AB"

*TYPE @TOKEN

,

*TYPE @TOKEN_POS

3

NOTE: That when scanning a string in a loop, an initial value of 0 can be placed in @TOKEN_POS and thus the following could be used:

*TYPE @EXTRACT (STRING_FIELD,BREAK_STRING,@TOKEN_POS+1,1S)

@FILE_EXISTS sae

Returns information about the state of a System File.  The sae must equate to a System File name of 39 characters or less; the default extension is CMD, if none is specified.  The string returned is one of the following:

Example:

TYPE @FILE_EXISTS ("U1:[ACC.APS]SALES.DS")

YES

@FILE_SIZE sae

This System Function returns a value that is the machine unit size of a existing system disk file, or -1 if the file does not exist.  The "machine unit" size is in bytes.  The OpenVMS file record padding affects the returned value.

This System Function should be used with the @FILE_EXISTS System Function, which returns a more comprehensive file status.

@FILE_SIZE (str_exp)

*TYPE @FILE_SIZE("MYFILE.DAT")

18

@GET_tablename_LOGICAL ("logical")

Returns the string defined for the specified logical from different logical name tables (GROUP, JOB, PROCESS, SYSTEM).  An empty string of blanks will be displayed if the given logical is not defined.  This is useful to see if, how, and where a logical is defined.

*TYPE @GET_GROUP_LOGICAL ("SYSTEM")

SYS$EXAMPLES:[TEST1]

*TYPE @GET_JOB_LOGICAL ("SYS$LOGIN_DEVICE")

SYS$USER2:

*TYPE @GET_PROCESS_LOGICAL ("NIS")

SYS4$DRA0:[ACCENTV1178]

*TYPE @GET_SYSTEM_LOGICAL ("NIS")

SYS4$SYSDEVICE:[ACCENT1178]

@HSTR  (decimal_value [,  length])

Returns the hexadecimal string for a given decimal value.  @HSTR will return asterisks if the specified length is too short for the value returned.  Example:

TYPE @HSTR(90,5)

0005A

@HVAL ("hexadecimal")

Returns the decimal value of the hexadecimal argument.  Example:

TYPE @HVAL("12AB")

4779

@IDATE date

Returns an integer numerically equivalent to the date value.  The integer is eight digits, including four digits for the year, and is always in the form YYYYMMDD.  Example:

*TYPE @DATE,2B,@IDATE @DATE

03/27/97 19970327

@IDAY date

Returns an integer between 1 and 31 that represents the day of the month specified in the date argument. Example:

*TYPE @DATE,2B,@IDAY @DATE

03/27/97 27

@IFIX ae

Returns an integer value from a real or numeric value by truncating . Example:

*TYPE @IFIX (10.999 - 1) 9

@IHOUR date

Returns an integer between 1 and 24 that represents the hour of the date and time value specified in the date argument. Example:

*TYPE @IHOUR @DTVAL("5-MAY-1997 1:21:14")

1

@IMAX (\\ae\\)

Returns the maximum integer value of all the values given.  Numeric values are rounded before comparison.  Example:

*TYPE @IMAX (17.3/2,85,33.97,2*47.39)

95

@IMIN (\\ae\\)

Returns the minimum integer value of all the values given.  Numeric values are rounded before comparison.  Example:

*TYPE @IMIN (17.3/2,85,33.97,2*47.39) 9

@IMINUTE date time

Returns an integer between 0 and 59 that represents the minute of the date and time value specified in the date argument.  Example:

*TYPE @IMINUTE @DTVAL("5-MAY-1997 1:21:14")

21

@IMONTH date time

Returns an integer between 1 and 12 representing the month specified by the date argument.  Example:

*TYPE @DATE,5B,@IMONTH @DATE

 09/07/ 97 9

@INDEX (str1,str2 [,ae])

Returns an integer value representing the position in str1 at which str2 begins. ae specifies the position at which the search is to begin. If ae is zero, negative, or omitted, it's assumed to be 1.

Numeric values of ae are rounded to integers before the calculation.  If str2 is not found, @INDEX returns zero.  @INDEX can handle lower case strings under the control of the ENABLE/DISABLE SEQUENCE LOWER option.  Exact case match is not needed for strings when SEQUENCE LOWER is disabled.  Example:

*SET "CHAPTER 5: STOCKS " TO @STRING

*TYPE "THE CHAPTER NUMBER IS THE ",&

@INDEX (@STRING,"5"), "TH CHARACTER IN & THE STRING

THE CHAPTER NUMBER IS THE 9TH CHARACTER IN THE STRING

@INT ae

TYPE @INT 1.41

1

TYPE @INT 1.52

2

TYPE @INT (-1.4) -1

-2

TYPE @INT (-1.5) -2

-4

An overflow conversion error returns either plus or minus 34359738367.

@ISECOND date time

Returns an integer between 0 and 59 that represents the second of the data and time value specified in the argument.  Example:

*TYPE @ISECOND @DTVAL ("5-MAY-1997 1:21:14")

14

@IVAL str

Returns the integer value represented by str, where str can contain only the digits 0 through 9 and a leading plus or minus sign.  Leading and trailing blanks are ignored.  The operator INTEGRAL can be used to test str before @IVAL is called.  Inappropriate characters or imbedded blanks cause a conversion error, and zero is returned.  If str has too many digits, an overflow error results, and @IVAL returns plus or minus 34359738367.  Example:

*TYPE @IVAL "5793 "

5793

@IYEAR date time

Returns a four-digit integer representing the year specified in a date argument.  Example:

*TYPE @DATE,5B,@IYEAR @DATE 09/07/97

1997

@LC str

Returns a string in which all upper case letters are converted to lower case.  Other characters are unchanged in the returned value.  Example:

*TYPE @LC "STRiNG"

 string

@LEFT (str, ae)

Returns a string containing the leftmost ae characters of str.  If ae is greater than the length of str, the whole string is returned.  If ae is zero or negative, a null string is returned.  A numeric ae will be converted to integer before processing.  Example:

SET 'CHAPTER 5 IN STOCK' TO @STRING

*TYPE @LEFT (@STRING,9)

CHAPTER 5

@LEN str

Returns an integer representing the number of characters in str.  It counts all characters of the string value.  Trailing spaces are ignored if FIELDTRIM is enabled (default).  Example:

SET 'ABCDE ' TO @STRING

*TYPE @LEN @STRING

5

*DISABLE FIELDTRIM

*TYPE @LEN @STRING

8

@LN ae

Returns the natural (base E) logarithm of the argument.  If ae is an integer, it is converted to numeric before processing.  Example:

*TYPE @LN 5,2B,@LN 20,2B,@LN 100

 1.6094379  2.9957323  4.6051702

@LOG ae

Returns the common (base 10) logarithm of the argument.  If ae is an integer, it is converted to numeric before processing.  Example:

*TYPE @LOG 5,2B,@LOG 20,2B,@LOG 100

.69897 1.30103 2

@LOG2 ae

Returns the base 2 logarithm of the argument.  If ae is an integer, it is converted to numeric before processing.  Example:

*TYPE @LOG2 5,2B,@LOG2 20,2B,@LOG2 100

2.3219281 4.3219281 6.643856

@LPAD (str, ae)

Returns a version of the input string str that has been either padded on the left with blanks or truncated on the left, to make it exactly the number of spaces specified by ae.  If ae is zero or negative, a null string is returned.  If it is numeric, it is rounded to an integer before processing.  Example:

*TYPE # ,@LPAD (SEVENTEEN ,7), # ,@LPAD (SIX",7), #

#VENTEEN# SIX#

@LTRIM str

Returns a string representing str with leading blanks deleted.  Example:

*TYPE "FIVE ",@LTRIM " COMPUTERS"

FIVE COMPUTERS

@MAKDAT (ae1,ae2,ae3)

Returns a full date when ae1, ae2, and ae3 represent, respectively, the year, month, and day.  Numeric values for any ae are rounded to integers.  Example:

*TYPE @MAKDAT (97,08,30)

08/30/1997

@MAKUDT

See Universal Date and Time Functions later in this section.

@NMAX (\\ae\\)

Returns the numeric maximum of the listed values.  Example:

*TYPE @NMAX (71.50,305.99,15)

305.99

@NMIN (\\ae\\)

Returns the numeric minimum of the listed values. Example:

*TYPE @NMIN (71.50,305.99,15)

15

@NUM ae

Returns a numeric value for an integer or real argument.  Example:

*TYPE @NUM 15,2B,@NUM 15/2

15  7.5

@NVAL str

Returns a numeric value represented by a character string argument, where str can contain only digits, a sign, and a decimal point, or exponential representation of a numeric value.  Leading and trailing blanks are ignored.  The relational operator NUMERIC can be used to test str before @NVAL is called.  Inappropriate characters result in a conversion error, and the value returned is 0.0.  If the string contains too many digits or an exponent > 38 , an overflow error results.  Value must be between approximately 1.7E38 and approximately -1.7E38.   Example:

*SET "53.79" TO @STRING(1)

*SET "5E2" TO @STRING(2)

*TYPE @NVAL @STRING(1),4B,@NVAL @STRING(2)

53.79 500

@OSTR (decimal_value [, length])

Returns the octal string for a given decimal value.  @OSTR will return asterisks if the specified length is too short for the value returned.  Example:

TYPE @OSTR(78,5)

00116

@OVAL ("octal_value")

Returns the decimal value of the octal argument.  Example:

*TYPE @OVAL("437")

287

@PI

Returns the value of pi, 3.141592653589793.  This function takes no arguments.  Example:

*TYPE @PI * 15

47.12389

@PS {"string"; (expression)}

This function allows for the embedding of special strings into a report output without altering the value in @PPOS.  @PS can be used for escape sequences to enable or disable printer-specific attributes (like underlining) without affecting the normal, visible columnar alignment of displayed text (which is produced by TAB TO or CENTER).  Example:

PRINT @PS (@ESC+"[7m"), "Inverse me", @PS(@ESC+"[0m")

INVERSE ME

NOTES:  @PS accepts a string argument or an expression in parentheses.  A new string is produced which is flanked by special control codes.  These control codes cause special processing to be done during the execution of a reporting Process Module (PM). Any string that is altered by @PS is considered special in that the value in @PPOS will not change when the string is displayed.

@RADIANS ae

Returns the radians of a degree argument.  Example:

*TYPE @RADIANS.9

.015707963

@RANDOM

Returns a number between zero and .999 999 999.  ACCENT R has a default starting point for the pseudo random number sequence.  However, the starting point can be controlled by setting a value to system field @RANDOMIZE.  Example:

*TYPE @RANDOM

.19494073

@REAL ae

Returns the real value for an integer or numeric argument.  Example:

*TYPE @REAL 719.37

719.37

@REPORT ae

Returns one of three string values, FILE, TERM, or NONE, to specify the destination of the report whose number is given by ae.  This function is meaningful only in a PM that generates reports.

@RIGHT (str, ae)

Returns a string representing the rightmost ae characters of str.  If ae is greater than the length of str, the whole string will be returned.  A null string will be returned if ae is zero or negative.  A numeric ae will be converted to integer before processing.  Example:

*TYPE @RIGHT (NO DEAL ,4)

DEAL

@RMAX (\\rae\\)

Returns the maximum value of a group of real values.  Example:

*TYPE @RMAX (32.2,37,69)

69

@RMIN (\\rae\\)

Returns the minimum value of a group of real values.  Example:

*TYPE @RMIN (23,17.34,17.6)

17.34

@RND (ae1[,ae2])

Returns the value of ae1 rounded to the number of places specified by ae2.  If ae2 is omitted, two decimal places are assumed.  If ae2 is negative, the integer part of ae1 is rounded.  If ae2 is positive, the fractional part of ae1 is rounded.  If ae2 is numeric, it is first rounded to an integer.

When @RND is used with any of the inter-record functions in a PM, the order of usage is important:

• @RND SUM AMT is the value of SUM AMT rounded after the summation.
• SUM @RND AMT is the sum of AMT values, each being rounded before summation.

Example:

*TYPE @RND (17.587,1),@CR,@RND (117,-1)

17.6

120

@RPAD (str, ae)

Returns a version of the input str that has been either padded on the right with blanks or truncated on the right to fit the length specified by ae.  If ae is zero or negative, a null string is returned.  If it is numeric, it is rounded to an integer before processing.  Example:

*TYPE # , @RPAD (SIX,5),#,@RPAD(SEVENTEEN,5),#

#SIX #SEVEN#

@RPT (str, ae)

Returns a string representing str repeated ae times.  The length of the repeated string is limited only by memory size.  If ae is zero or negative, a null string is returned.  If it is numeric, it is first rounded to an integer.  @RPT trims trailing blanks from variables but not from literals.  Example:

*TYPE @RPT (# ,5)

 # # # # #

@RTRIM str

Returns a string representing str with trailing blanks deleted. Example:

*TYPE @RTRIM COMPUTERS: ,5

 COMPUTERS:5

@RVAL

Returns a real value represented by a character string argument, where str can contain only digits, a sign, and a decimal point, or exponential representation of a numeric value.  Leading and trailing blanks are ignored.  The relational operator NUMERIC can be used to test str before @RVAL is called.   Inappropriate characters result in a conversion error, and the value 0.0 is returned.  If the string contains too many digits or an exponent > 38 , an overflow error results.  Value must be between approximately 1.7E38 and approximately -1.7E38.  Example:

*SET '53.79' TO @STRING(1)

*TYPE @RVAL @STRING(1) IF @STRING(1) NUMERIC

 53.79

@SECONDS_DIFF (dae1, dae2)

Finds the difference between two extended date and time values.  The output is a numeric value of seconds and fractions thereof.

*TYPE @DATE_DIFF (@DATVAL(6-MAY-1993 12:30:21.43),

 @DTVAL(6-MAY-1993 11:47:18.21")

2583.22

@SECONDS_DIFF_STR ae

Given the numeric difference between two dates (as would be returned by the @SECONDS_DIFF function), this function produces a string of form:

"[[hh:]mm:]ss: also describable as "ss", "mm:ss", and "hh:mm:ss"

where:      hh - represents hours(0. . .N)

            mm - represents minutes per: 0<=mm<60

            ss - represents seconds per: 0<=ss<60

The "smallest" string will be used to display the value; in other words, if the difference is only 15 seconds, then the returned string value will be "15" and not "0:00:15" )

@SGN ae

Returns an integer value of 1 if ae is greater than zero, 0 if ae is zero and -1 if ae is less than zero.  Example:

*TYPE @INTEGER(1),2B,@INTEGER(2),2B,& @INTEGER(3)

 17 0 -17

*TYPE @SGN @INTEGER(1),2B,@SGN @INTEGER(2),2B,@SGN @INTEGER(3)

 1 0 -1

@SIN ae

Returns the sine of the argument expressed in degrees.  Example:

*TYPE @SIN .9 .015707317

@SINR ae

Returns the sine of the argument expressed in radians.  Example:

*TYPE @SINR .9

 .78332691

@SMAX (\\str\\)

Returns the highest value found per the ASCII collating sequence; that is, the value that would be last if the strings were sorted with ENABLE SEQUENCE LOWER in effect.  Example:

*TYPE @SMAX (YES, =, yes)

 yes

@SMIN (\\str\\)

Returns the lowest value found per the ASCII collating sequence; that is, the value that would be first if the strings were sorted with ENABLE SEQUENCE LOWER in effect.  The example for @SMAX shows the ASCII code for the first character of each string used in the example below:

TYPE @SMIN (YES, =, YES)

=

@SOUNDEX (string)

Returns a four-character alphanumeric-coded string (by breaking down a word using Soundex coding patterned after phonetic rules).

@SOUNDEX is useful in detecting subtle English-language homophones and spelling differences for inquiry, search, and purge applications.  Example:

*TYPE @SOUNDEX (ALAN)

A450

Soundex Code      Entry Strings

     A450      Alan,Allan,Allen,Alynne

     C640      Carol,Carole,Carroll

     G620      George,Georg,Greg

     M600      Maria,Marie, Mary, Merry, Moria

Rules of Soundex coding:

1. Retain the first letter (converting to uppercase if necessary).
2. Ignore all non-alphabetic characters and the letters A, E, I, O, U, Y, W, and H if they were not the first letters of the string.
3. Replace second and subsequent characters by a group digit code.

Code  Letter Group

 1      B,F,P,V

 2      C,G,J,K,Q,S,X,Z

 3      D,T

 4      L

 5      M,N

 6      R

Collapse repeating consecutive group digits.  (Example:  an inner is considered the same as, etc.)

Truncate or zero-pad the result to a four-character string.  (Example:  a null-string input will produce)

@SPACE ae

Returns a string of ae spaces.  The length of the string is limited only by memory size.  If ae is zero or negative, a null string will be returned.  If ae is numeric, it will be rounded to an integer.  If a constant number of spaces is needed, it is more efficient to use nB or nS.  Example:

*TYPE "#",3B,"#",@SPACE 3,

"#"

# # #

@SPAN (str1,str2)

Returns the portion of str1 that follows the first occurrence of any character in str2.  The break character is stored in @TOKEN.  If none of the characters in str2 are found in str1, a null value is returned and @TOKEN contains a null.

If str2 is null, the value of @SPAN is null and @TOKEN contains a null.  See @EXTRACT  or @BREAK for returning the other portion of str1.  If str2 is a field name, and if one of the values in the field is a space, the space should not be the final character in the field, since it might be truncated, particularly if FIELDTRIM is enabled.  @SPAN can handle lower case strings under the control of the ENABLE/DISABLE SEQUENCE LOWER option.  Exact case match is no longer needed for strings when SEQUENCE LOWER is disabled.  In appropriate cases, the @TOKEN value is returned as it appears in its source string.  Its case will not be altered although it may have matched a different case item.  Example:

*TYPE @SPAN ("AB, CD/EF",",/")

CD/EF

*TYPE @TOKEN

@SQRT ae

Returns a numeric value that is the square root of ae.  If ae is an integer, it is converted to numeric before processing.  If ae is a negative value, a warning message is displayed, and the square root of the absolute value of ae is returned.  Example:

*TYPE @SQRT 25,2B,@SQRT 79

5 8.8881944

@STR (ae[,"format"])

Returns a character string representing ae in free form or in the form specified by format (see Picture Formats ).  If an explicit format causes a conversion error, the returned string contains all asterisks.  Values having more than eight digits are displayed in exponential form unless a format is specified. Example:

*SET 123456789 TO @INTEGER

*TYPE @INTEGER

123456789

*TYPE @STR @INTEGER

 1.23456789E+08

*TYPE @STR (@INTEGER,"10D")

0123456789

@SUBSTR  (str,ae1 [,ae2])

Returns a string containing ae2 characters of str, beginning at character position ae1.  If ae2 is omitted, the returned string contains all characters from position ae1 to the end of str.  Both ae1 and ae2 will be converted to integer if they are numeric.  If ae1 is zero or negative, it is assumed to represent the first character of str.  If ae2 is zero, negative, or omitted, it will return a null string.  Example:

*TYPE @SUBSTR ("PLEASE ANSWER YES",8,6)

ANSWER

@TAN ae

Returns the tangent of the argument expressed in degrees. Example:

*TYPE @TAN .9

.015709255

@TANR ae

Returns the tangent of the argument expressed in radians.  Example:

*TYPE @TANR .91

.2601582

@TIME_STAMP TO  numeric_field

Returns a double-precision floating-point value having sufficient resolution to uniquely identify any event or instant in time.  This system function is used for qualifying tasks, activities, record updates, etc.

The numeric value returned by @TIME_STAMP is formatted:

• YYYYMMDD.FFFFFFFF

Where:

• YYYYMMDD - represents the present year, month and day.
• FFFFFFFF - represents the present fraction of a day since midnight.

To see the entire time stamp, use a print picture of "8D.10D".

The @TIME_STAMP value may be used to display the date and time of an ACCENT R event per the following example.

When run (& the value of @TIME_STAMP is 19910825.52426839), it produces:

08/25/1991 12:34:56.789 

Example:

DECLARE

Event_Stamp,FLOAT,max

Event_Date,FULLDATE

Event_Time,INT,8

Event_Hour,INT,2

Event_Minute,INT,2,PP= DD

Event_Second,INT,2,PP= DD

Event_mSec,INT,3,PP= DDD

! mSec = milliseconds.

DETAIL

@TIME_STAMP to Event_Stamp

@DVAL @STR @IFIX Event_Stamp to Event_Date

86400000*(Event_Stamp - @IFIX(Event_Stamp))& to Event_Time

Event_Time mod 3600000 to Event_Minute

Event_Time / 3600000 to Event_Hour

Event_Minute mod 60000 to Event_Second

Event_Minute / 60000 to Event_Minute

Event_Second mod 1000 to Event_mSec

Event_Second / 1000 to Event_Second

Type @DATSTR Event_Date,2s,nocr

Type Event_Hour,":",Event_Minute,":",nocr

Type Event_Second,".",Event_mSec

The difference between two @TIME_STAMP values is a value of the form DDDD.FFFFFFFF where DDDD is the number of whole days and FFFFFFFF is the additional fractional part of a day.

@TRUNC (ae1[,ae2])

Returns the value of ae1 truncated as specified by ae2.  If ae2 is omitted, 2 decimal places are assumed.  If ae2 is negative, the integer part of ae1 is truncated.  If ae2 is zero or positive, the fractional part of ae1 is truncated.  If ae2 is numeric, it is first rounded to an integer.

When @TRUNC is used with any of the inter-record functions in a PM, the order of usage is important.

• @TRUNC SUM AMT is the value of SUM AMT truncated after summation.
• SUM @TRUNC AMT is the sum of AMT values, each being truncated before summation.

Example:

*TYPE @TRUNC (17.587,1),25B,@TRUNC(117,-1)

 17.5 110

@UC str

Returns a string in which lower-case alphabetic characters are converted to upper-case characters.  Other characters are unchanged in the output.  Example:

*TYPE @UC "make THIS aLL caps"

MAKE THIS ALL CAPS

@UDT

See Universal Date and Time Functions at the end of this chapter.

@UDTHRS

See Universal Date and Time Functions at the end of this chapter.

@UDTSTR

See Universal Date and Time Functions at the end of this chapter.

@UNITS

The integer number of milliseconds of CPU time used in ACCENT R since beginning the current session.  The value is updated at the beginning of each command execution.  Example:

*TYPE @UNITS

39190

@WKDAY date

Returns an integer representing the day of the week contained in date. Returned values are the integers 1 through 7, representing, respectively, Sunday through Saturday.  Example:

*TYPE "THIS IS DAY ", @WKDAY @DATE,  " OF THE WEEK."

THIS IS DAY 3 OF THE WEEK.

@YRDAY date

Returns an integer between 1 and 366 representing the day of the year implied by the date argument.  Example:

*TYPE "THIS IS DAY ",@YRDAY @DATE, " OF THE YEAR."

THIS IS DAY 251 OF THE YEAR.

Universal Date and Time Functions

ACCENT R offers four functions supporting Smithsonian Astronomical Universal Date-Time Standard (UDT).  UDT values are integers that represent days since the base date November 17, 1858, and the decimal fractional part of a day relative to Greenwich Mean Time (GMT).  They provide an excellent means of storing date and time information and are easily converted to date and time values for display.

@UDT

Returns an integer value that represents the current UDT.  A Schema Definition, Global Storage, or Working Storage field destined to receive UDT values should be declared Integer, 12

@MAKUDT (date, hours)

Returns a UDT value representing the date and time given, where date is a value from a date field or value returned by @DATE, @DVAL, @CAL, or @MAKDAT hours is a numeric value representing the hour and a decimal fraction thereof: for example, 5:45 PM would be expressed as 17.75.  The range of dates and times that can be created are from Nov 17, 1858, 00:00:00 through Sept 27, 2217, 23:59:59.  Attempting to create a UDT value outside that range results in a UDT either of Nov 17, 1858, 00:00:00 or Sept 27, 2217, 23:59:59.

NOTE: An hour value less than zero or >= 24 changes the date accordingly.  This function facilitates applications that require date and time arithmetic.  For example, the following expression adds three and one-half hours to a UDT value:

udt_value + @MAKUDT (@NODATE,3.5)

Using @NODATE as the base date in this expression causes @MAKUDT to create a value representing only a fractional part of a day.  The following expression adds one day to a UDT value:

udt_value + @MAKUDT (@NODATE,24)

@UDTSTR ae

Returns a 20- character string which is in the form dd-mmm-yyyy hh:mm:ss .  The argument, ae, can be an integer constant, integer-valued expression, bit field, function, or expression whose value is a UDT.  The date and time values returned are with respect to the time zone recorded in the system field @TIME_ZONE.  @TIME_ZONE is initialized by ACCENT R when it starts up and normally need not be changed.  The value in @TIME_ZONE reflects the time displacement as hours west to east of GMT (from 12 to -12, respectively).  On some systems the local time zone value may not be available and is thus recorded as zero; in this case, the UDT values are not strictly correct, but all uses that compare UDT values with one another on that system are correct.

@UDTHRS (ae1-ae2)

Returns a numeric value that represents the hours difference between ae1 and ae2, where ae can be an

integer constant, integer-valued expression, bit field, function, or expression.  The difference value is normally the result of subtracting one UDT value from another.  The returned value has the same sign as the input value; it is therefore generally preferable to subtract a smaller value (i.e., earlier UDT) from a larger value so that the difference is positive.

For these examples, two arbitrary date/time values have been set to Global Storage (GS) fields %UDT1 and %UDT2.  The first example shows those values.

*TYPE @UDTSTR %UDT1,5B,@UDTSTR %UDT2

29-Jun-1986 13:53:06 29-Jun-1986 15:00:55

The difference between these two values, expressed in days, is:

*TYPE @UDTHRS (%UDT2 - %UDT1)/24 @'5-.4D'

.0471

The difference in hours is:

*TYPE @UDTHRS (%UDT2 - %UDT1) @'5-.4D'

1.1302

The difference in minutes is:

*TYPE @UDTHRS (%UDT2 - %UDT1)*60 @'5-.4D'

67.8131

The difference In seconds is:

*TYPE @UDTHRS (%UDT2 - %UDT1)* 3600 @'5-.4D'

4068.7866

The following Command Module contains TYPE statements to show the difference in hours:  minutes:  seconds.  Using @INT instead of @IFIX or @TRUNC for the seconds part of the value minimizes apparent discrepancies.

*LIST CM UDT_PRINT

00100 TYPE @IFIX(@UDTHRS(%UDT2-%UDT1))@'14-',':',NOCR

00110 TYPE @IFIX((@UDTHRS(%UDT2-%UDT1)*60)MOD &

60)@’DD’,’:’,NOCR

00120 TYPE @INT((@UDTHRS(%UDT2-%UDT1)*3600)MOD 60)@’DD’

*USE CM UDT_PRINT

1:07:49

The next example adds 25 1/2 hours to the first UDT value.

*TYPE @UDTSTR (%UDT1 + @MAKUDT (@NODATE,25.5))

30-Jun-1991 15:23:06

The following example makes a UDT value for the date and time April 15, 1991, 5:32:24 pm, converts it to a string, then displays it.

*TYPE @UDTSTR (@MAKUDT(@DVAL ‘4-15-81’,17. + 32/60. + 24/3600.))

 15-Apr-1991 17:32:24

System Functions for Concurrent Processing

Concurrent processing means that more than one process can work cooperatively on a given application.  This is useful for on-line updating and terminal flexibility.  One user may have a process which handles terminal activity while another process searches a database.  Other users may have processes searching the same database.

The most common application is to signal the presence of additional data in a shared global section or a database.  Users who need the latest information from the same database can have continuous displays automatically updated with concurrent processing.  A user may have function keys that start another process for different tasks while the first process continues to monitor the database for updates.

Global sections are used for passing information between processes.  Event flag clusters are used to synchronize activities of the processes.  ACCENT R makes it easy to use the system service commands which adjust the flag clusters.

ACCENT R supports common event flag cluster operations with six new system functions.  These system functions call system service commands.  Common event flag clusters are shared among all processes in a User Identification Code (UIC) group.

• In ACCENT R, a shared global section is created and "mapped" by:

USE GS gs_name AS [PERM/ANENT/] {GROUP; SYSTEM} GLOBAL /SECTION/

• A shared global section is disassociated by:
  

  USE NO GS gs_name CANCEL

A common event cluster is identified by a name (length: 1 to 15 characters).  This "key" name is internally converted by ACCENT R to upper case.  The first ACCENT R process using a "key" causes association and allocation of the resource (if another process hasn’t already associated the event cluster).  The first association of an event cluster initializes all flags cleared.  The event cluster will automatically reallocate the resource when the last image process referencing the cluster is finished.

ACCENT R automatically handles the tedious details of event flag cluster association, setup and usage.  Internally, ACCENT R uses event cluster #2 whose flag values to OpenVMS are normally in the range 64 to 95 inclusive; the flag argument value (s) required by the new ACCENT R functions range from 1 to 32 inclusive.

A simple table of the correspondences is:

This usage requires a process’ "timer queue entry quota" to be sufficient.  (Timer quota relates to the number of entries allowed in the queue at a time.)  The system default value should be enough for normal operations.  An error message will be received if the quota is not enough.  The System Administrator must increase the quota (by running a program to update the User Authorization File (UAF)).  The quota can be displayed using the DCL command: SHOW PROCESS/QUOTA.

Real-time control of external devices is feasible because of the efficiency of the event flag mechanism.  Activation time (from the setting of the event flag by another process to the rescheduling of the waiting process) averages between 10 to 20 milliseconds.

NOTE:  This value is to be used as a guideline only (time will vary based on system load).

Use of @EVENT_READ permits a synchronous operation of multiple processes; synchronous operation is effected using any of the @EVENT_WAIT functions.

For specific event flag programming considerations in a 3GL program and/or for use communicating with ACCENT R, see the chapter "EVENT FLAG SERVICES" in the OpenVMS "Introduction to System Services" manual.  Shared-memory, multiple-CPU, common event cluster usage and SYSGEN setup is documented in the "USING SHARED MEMORY" appendix of the same manual.