8.texi

@comment *********************************************************************
@comment ** 8. Functions                                                    **
@comment *********************************************************************
@newchapter{8,Functions}
@menu
* 8.1:  Intrinsic Functions.
* 8.2:  Built-In System Subroutines.
@end menu
@newsection{8.1,Intrinsic Functions}
GnuCOBOL supports a wide variety of ``intrinsic functions'' that may be used anywhere in the PROCEDURE DIVISION where a literal is allowed.  For example:

@example

MOVE FUNCTION LENGTH(Employee-Last-Name) TO Employee-LN-Len

@end example

Note how the word @code{FUNCTION} is part of the syntax when you use an intrinsic function.  You can use intrinsic functions without having to include the reserved word @code{FUNCTION} via settings in the @syntaxref{REPOSITORY} paragraph.  You may accomplish the same thing by specifying the
@switchidx{-fintrinsics} to the GnuCOBOL compiler when you compile your programs.

User-written functions (@pxref{Subprogram Types}) never require the @code{FUNCTION} keyword when they are executed, because each user-written function a program uses @i{must} be included in that program's @code{REPOSITORY} paragraph, which therefore makes the @code{FUNCTION} keyword optional.

The following intrinsic functions, known to other ``dialects'' of COBOL, are defined to GnuCOBOL as reserved words but are not otherwise implemented currently.  Any attempts to use these functions will result in a compile-time error message. However they are described at the end of this chapter.

@example
BOOLEAN-OF-INTEGER
CHAR-NATIONAL
DISPLAY-OF
EXCEPTION-FILE-N
EXCEPTION-LOCATION-N
INTEGER-OF-BOOLEAN
NATIONAL-OF
STANDARD-COMPARE

@end example

@verbatim

Date and Time Formats
~~~~~~~~~~~~~~~~~~~~~

@end verbatim

For functions @code{FORMATTED-CURRENT-DATE}, @code{FORMATTED-DATE}, @code{FORMATTED-TIME}, and @code{FORMATTED-DATETIME}, the format literal argument indicates the format of the date or time value that is the result of the function. The result of the function will have the same type as its format literal, which can be alphanumeric, national or UTF-8.

For functions @code{INTEGER-OF-FORMATTED-DATE}, @code{SECONDS-FROM-FORMATTED-TIME}, and @code{TEST-FORMATTED-DATETIME}, the format literal indicates the format of the date or time value specified as the second argument of the function.

The permissible format strings are listed as follows. For a full description of each subfield in the format literals, including a range of permissible values in data associated with the formats, see the Value meanings and limits section.

@verbatim

Integer date form:
~~~~~~~~~~~~~~~~~

@end verbatim

A value in integer date form is a positive integer that represents the number of days since 31 December, 1600 in the Gregorian calendar.

It must be greater than zero and less than or equal to the value of FUNCTION INTEGER-OF-DATE (99991231), which is 3,067,671.

@verbatim

Standard date form:
~~~~~~~~~~~~~~~~~~

@end verbatim

A value in standard date form is an integer of the form YYYYMMDD, calculated using (YYYY * 10,000) + (MM * 100) + DD, where:

YYYY represents the year in the Gregorian calendar. It must be an integer in the range [1601, 9999].

MM represents a month and must be an integer in the range [01, 12].

DD represents a day and must be an integer in the range [01, 31], valid for the specified month and year combination.

@verbatim

Julian date form:
~~~~~~~~~~~~~~~~

@end verbatim

A value in Julian date form is an integer of the form YYYYDDD, calculated using (YYYY * 1000) + DDD, where:

YYYY represents the year in the Gregorian calendar. It must be an integer in the range [1601, 9999].

DDD represents the day of the year. It must be a positive integer in the range [1, 366], valid for the year specified.

@verbatim

UTC offset value:
~~~~~~~~~~~~~~~~

@end verbatim

A UTC offset value is an integer representation of offset from UTC (Coordinated Universal Time) expressed in minutes. The value must be greater than or equal to -1439 and less than or equal to 1439.

Note: The offset value 1439 represents 23 hours 59 minutes, which is one minute less than a day.
Standard numeric time form

A value in standard numeric time form is a numeric value representing seconds past midnight. The value must be greater than or equal to zero and less than 86,400

@verbatim

Date and time formats:
~~~~~~~~~~~~~~~~~~~~~

@end verbatim

For functions @code{FORMATTED-CURRENT-DATE}, @code{FORMATTED-DATE}, @code{FORMATTED-TIME}, and @code{FORMATTED-DATETIME}, the format literal argument indicates the format of the date or time value that is the result of the function. The result of the function will have the same type as its format literal, which can be alphanumeric, national or UTF-8.

For functions @code{INTEGER-OF-FORMATTED-DATE}, @code{SECONDS-FROM-FORMATTED-TIME}, and @code{TEST-FORMATTED-DATETIME}, the format literal indicates the format of the date or time value specified as the second argument of the function.

The permissible format strings are listed as follows. For a full description of each subfield in the format literals, including a range of permissible values in data associated with the formats, see Value meanings and limits.

@verbatim

Date formats            Format literals
~~~~~~~~~~~~            ~~~~~~~~~~~~~~~

Basic calendar date     YYYYMMDD
Extended calendar date  YYYY-MM-DD
Basic ordinal date      YYYYDDD
Extended ordinal date   YYYY-DDD
Basic week date         YYYYWwwD
Extended week date      YYYY-Www-D

Integer-seconds time formats:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Integer-seconds time formats            Format literals

Basic local time                        hhmmss
Extended local time                     hh:mm:ss
Basic Coordinated Universal Time (UTC) 	hhmmssZ
Extended UTC time                       hh:mm:ssZ
Basic offset time                       hhmmss+hhmm
Extended offset time                   	hh:mm:ss+hh:mm

Fractional-seconds time formats:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fractional-seconds time formats         Format literals
Basic local time                        hhmmss.ssss
Extended local time                     hh:mm:ss.ssss
Basic Coordinated Universal Time (UTC) 	hhmmss.ssssZ
Extended UTC time                       hh:mm:ss.ssssZ
Basic offset time                       hhmmss.ssss+hhmm
Extended offset time                    hh:mm:ss.ssss+hh:mm

@end verbatim

Note: The period is used as the decimal separator, and four "s" characters after the period are used for illustrative purposes. The number of "s" characters that might be specified after the decimal separator in these formats might range from 1 to 9.

@verbatim

Value meanings and limits:
~~~~~~~~~~~~~~~~~~~~~~~~~

The permissible date and time formats have the following meanings and limits:

Format    Meaning and limits
YYYY      Year, 1601-9999
MM        Month, 01-12
DD        Day of month, 01-{28|29|30|31} dependent on month sub-field
DDD       Day of year for ordinal date formats, 001-365|366
ww        Week of year, 01-53
D         Day of week, 1-7
W
-
hh        Hours, 00-23
mm        Minutes, 00-59
ss        Seconds, 00-59
.s        Fractional seconds, always prefixed with '.' then 1-9 's'
+|-hh:mm  UTC offset hours (extended times only), the offset can be adjusted
          upward (by a '+' prefix) or downward (by a - prefix). A prefix of 0
          (zero) indicates that an offset of UTC is not available on the system.
Z         UTC time indicator

@end verbatim


@verbatim

Value meanings and limits:
~~~~~~~~~~~~~~~~~~~~~~~~~

The permissible date and time formats have the following meanings and limits:

Format 	Meaning and limits:
~~~~~~~~~~~~~~~~~~~~~~~~~~

YYYY      Year, 1601-9999
MM        Month, 01-12
DD        Day of month, 01-{28|29|30|31} dependent on month sub-field
DDD       Day of year for ordinal date formats, 001-365|366
ww        Week of year, 01-53
D         Day of week, 1-7
W
-
hh        Hours, 00-23
mm        Minutes, 00-59
ss        Seconds, 00-59
.s        Fractional seconds, always prefixed with '.' then 1-9 's'
+|-hh:mm  UTC offset hours (extended times only), the offset can be adjusted
          upward (by a '+' prefix) or downward (by a - prefix).

          A prefix of 0 (zero) indicates that an offset of UTC is not available
          on the system.
Z 	       UTC time indicator

@end verbatim


The supported intrinsic functions are listed in the following sections, along with their syntax and usage notes.
@menu
* 8.1.1:   ABS
* 8.1.2:   ACOS
* 8.1.3:   ANNUITY
* 8.1.4:   ASIN
* 8.1.5:   ATAN
* 8.1.6:   BIT-OF
* 8.1.7:   BIT-TO-CHAR
* 8.1.8:   BYTE-LENGTH
* 8.1.9:   CHAR
* 8.1.10:  COMBINED-DATETIME
* 8.1.11:  CONCAT
* 8.1.11:  CONCATENATE
* 8.1.12:  CONTENT-LENGTH
* 8.1.13:  CONTENT-OF
* 8.1.14:  COS
* 8.1.15:  CURRENCY-SYMBOL
* 8.1.16:  CURRENT-DATE
* 8.1.17:  DATE-OF-INTEGER
* 8.1.18:  DATE-TO-YYYYMMDD
* 8.1.19:  DAY-OF-INTEGER
* 8.1.20:  DAY-TO-YYYYDDD
* 8.1.21:  E
* 8.1.22:  EXCEPTION-FILE
* 8.1.23:  EXCEPTION-LOCATION
* 8.1.24:  EXCEPTION-STATEMENT
* 8.1.25:  EXCEPTION-STATUS
* 8.1.26:  EXP
* 8.1.27:  EXP10
* 8.1.28:  FACTORIAL
* 8.1.29:  FORMATTED-CURRENT-DATE
* 8.1.30:  FORMATTED-DATE
* 8.1.31:  FORMATTED-DATETIME
* 8.1.32:  FORMATTED-TIME
* 8.1.33:  FRACTION-PART
* 8.1.34:  HEX-OF
* 8.1.35:  HEX-TO-CHAR
* 8.1.36:  HIGHEST-ALGEBRAIC
* 8.1.37:  INTEGER
* 8.1.38:  INTEGER-OF-DATE
* 8.1.39:  INTEGER-OF-DAY
* 8.1.40:  INTEGER-OF-FORMATTED-DATE
* 8.1.41:  INTEGER-PART
* 8.1.42:  LENGTH
* 8.1.43:  LENGTH-AN
* 8.1.44:  LOCALE-COMPARE
* 8.1.45:  LOCALE-DATE
* 8.1.46:  LOCALE-TIME
* 8.1.47:  LOCALE-TIME-FROM-SECONDS
* 8.1.48:  LOG
* 8.1.49:  LOG10
* 8.1.50:  LOWER-CASE
* 8.1.51:  LOWEST-ALGEBRAIC
* 8.1.52:  MAX
* 8.1.53:  MEAN
* 8.1.54:  MEDIAN
* 8.1.55:  MIDRANGE
* 8.1.56:  MIN
* 8.1.57:  MOD
* 8.1.58:  MODULE-CALLER-ID
* 8.1.59:  MODULE-DATE
* 8.1.60:  MODULE-FORMATTED-DATE
* 8.1.61:  MODULE-ID
* 8.1.62:  MODULE-PATH
* 8.1.63:  MODULE-SOURCE
* 8.1.64:  MODULE-TIME
* 8.1.65:  MONETARY-DECIMAL-POINT
* 8.1.66:  MONETARY-THOUSANDS-SEPARATOR
* 8.1.67:  NUMERIC-DECIMAL-POINT
* 8.1.68:  NUMERIC-THOUSANDS-SEPARATOR
* 8.1.69:  NUMVAL
* 8.1.70:  NUMVAL-C
* 8.1.70B: NUMVAL-C-2
* 8.1.71:  NUMVAL-F
* 8.1.72:  ORD
* 8.1.73:  ORD-MAX
* 8.1.74:  ORD-MIN
* 8.1.75:  PI
* 8.1.76:  PRESENT-VALUE
* 8.1.77:  RANDOM
* 8.1.78:  RANGE
* 8.1.79:  REM
* 8.1.80:  REVERSE
* 8.1.81:  SECONDS-FROM-FORMATTED-TIME
* 8.1.82:  SECONDS-PAST-MIDNIGHT
* 8.1.83:  SIGN
* 8.1.84:  SIN
* 8.1.85:  SQRT
* 8.1.86:  STANDARD-DEVIATION
* 8.1.87:  STORED-CHAR-LENGTH
* 8.1.88:  SUBSTITUTE
* 8.1.89:  SUBSTITUTE-CASE
* 8.1.90:  SUM
* 8.1.91:  TAN
* 8.1.92:  TEST-DATE-YYYYMMDD
* 8.1.93:  TEST-DAY-YYYYDDD
* 8.1.94:  TEST-FORMATTED-DATETIME
* 8.1.95:  TEST-NUMVAL
* 8.1.96:  TEST-NUMVAL-C
* 8.1.97:  TEST-NUMVAL-F
* 8.1.98:  TRIM
* 8.1.99:  UPPER-CASE
* 8.1.100: VARIANCE
* 8.1.101: WHEN-COMPILED
* 8.1.102: YEAR-TO-YYYY
* 8.1.103: BOOLEAN-OF-INTEGER
* 8.1.104: CHAR-NATIONAL
* 8.1.105: DISPLAY-OF
* 8.1.106: EXCEPTION-FILE-N
* 8.1.107: EXCEPTION-LOCATION-N
* 8.1.108: INTEGER-OF-BOOLEAN
* 8.1.109: NATIONAL-OF
* 8.1.110: STANDARD-COMPARE

@end menu
@comment *********************************************************************
@comment ** 8.1.1 ABS                                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.1,ABS}
@diagram{ABS Function,FN-ABS,FN-ABS,None}
This function determines and returns the absolute value of @var{number} (a numeric literal or data item) supplied as an argument.

Note that @code{ABSOLUTE-VALUE} has an alias for this function.
@comment *********************************************************************
@comment ** 8.1.2 ACOS                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.2,ACOS}
@diagram{ACOS Function,FN-ACOS,FN-ACOS,None}
The @code{ACOS} function determines and returns the trigonometric arc-cosine, or inverse cosine, of @var{cosine} value (a numeric literal or data item) supplied as an argument.

The result will be an angle, expressed in radians.  You may convert this to an angle measured in degrees, as follows:

@example
COMPUTE @var{degrees} = ( @var{radians} * 180 ) / FUNCTION PI
@end example
@comment *********************************************************************
@comment ** 8.1.3 ANNUITY                                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.3,ANNUITY}
@diagram{ANNUITY Function,FN-ANNUITY,FN-ANNUITY,None}
This function returns a numeric value approximating the ratio of an annuity paid at @var{interest-rate} (numeric data item or literal) for each of @var{number-of-periods} (numeric data items or literals).

@var{interest-rate} is the rate of interest paid at each payment.  If you only have an annual interest rate and you wish to compute monthly annuity payments, divide the annual interest rate by 12 and use that value for @var{interest-rate}.

Multiply the result of this function times the desired principal amount to determine the amount of each period's payment.

A note for the financially challenged: an annuity is basically a reverse loan; an accountant would take the result of this function multiplied by -1 times the principal amount to compute a loan payment you are making.

@comment *********************************************************************
@comment ** 8.1.4 ASIN                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.4,ASIN}
@diagram{ASIN Function,FN-ASIN,FN-ASIN,None}
The @code{ASIN} function determines and returns the trigonometric arc-sine, or inverse sine, of @var{sine} value (a numeric literal or data item) supplied as an argument.

The result will be an angle, expressed in radians.  You may convert this to an angle measured in degrees, as follows:

@example
COMPUTE @var{degrees} = ( @var{radians} * 180 ) / FUNCTION PI
@end example
@comment *********************************************************************
@comment ** 8.1.5 ATAN                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.5,ATAN}
@diagram{ATAN Function,FN-ATAN,FN-ATAN,None}
Use this function to determine and return the trigonometric arc-tangent, or inverse tangent, of @var{tangent} value (a numeric literal or data item) supplied as an argument.

The result will be an angle, expressed in radians.  You may convert this to an angle measured in degrees, as follows:

@example
COMPUTE @var{degrees} = ( @var{radians} * 180 ) / FUNCTION PI
@end example
@comment *********************************************************************
@comment ** 8.1.6 BIT-OF                                                  **
@comment *********************************************************************
@page
@newsubsection{8.1.6,BIT-OF}
@diagram{BIT-OF Function,FN-BIT-OF,FN-BIT-OF,None}
@code{BIT-OF} function returns an alphanumeric character string of '1' and '0' characters, which represents the binary value of each byte in the argument used on input.
@enumerate
@item
The function type is alphanumeric.
@item
@var{argument-1} must be a data item, literal, or an intrinsic function result of any data class.
@end enumerate
@noindent
Returned values:

@enumerate
@item
An alphanumeric character string consisting of the binary representation of each byte in @var{argument-1}.
@item
The length of the character string returned, in bytes, is eight times the length of @var{argument-1}, in bytes.
@end enumerate

@example

        >>SOURCE FREE
*> Example of use of function BIT-OF
identification division.
program-id. pgmbitof.
environment division.
configuration section.
   repository. function all intrinsic.
data division.
working-storage section.
01 AAA PIC XXX VALUE "1 2".
01 BBB PIC XXX VALUE "A B".

procedure division.
  display BIT-OF(1)     at 0110
  display BIT-OF(2)     at 0210
  display BIT-OF(3)     at 0310
  display BIT-OF(0123)  at 0410
  display BIT-OF(AAA)   at 0510
  display BIT-OF(BBB)   at 0610
  accept omitted
  stop run.

Produces :

00110001
00110010
00110011
00110000001100010011001000110011
001100010010000000110010
010000010010000001000010

@end example

@comment *********************************************************************
@comment ** 8.1.7 BIT-TO-CHAR                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.7,BIT-TO-CHAR}
@diagram{BIT-TO-CHAR Function,FN-BIT-TO-CHAR,FN-BIT-TO-CHAR,None}
@code{BIT-TO-CHAR} function returns a character string that represents a bit pattern supplied on input.
@enumerate
@item
The function type is alphanumeric.
@item
@var{argument-1} must be an alphanumeric literal, alphanumeric data item, or alphanumeric group item.
@item
@var{argument-1} must consist only of the characters "0" and "1".
@item
The length of @var{argument-1} must be a multiple of 8 bytes.
@end enumerate

@noindent
Returned values:
@enumerate
@item
A character string consisting of bytes representing the sequence of "0" and "1" characters in @var{argument-1}.
@item
The length of the result string is equal to the length of the input string divided by 8.
@end enumerate

@example

        >>SOURCE FREE
*> Example of use of function BIT-TO-CHAR
identification division.
program-id. pgmbittochar.
environment division.
configuration section.
  repository. function all intrinsic.
data division.
working-storage section.
01 AAA PIC X(8) VALUE "0110000".

procedure division.
  display BIT-TO-CHAR("00110000") at 0610
  display BIT-TO-CHAR("00110001") at 0710
  display BIT-TO-CHAR("00110010") at 0810
  display BIT-TO-CHAR("00110011") at 0910
  display BIT-TO-CHAR(AAA)        at 1010
  accept omitted
  stop run.

Produces:

    0
    1
    2
    3
    a

@end example

@comment *********************************************************************
@comment ** 8.1.8 BYTE-LENGTH                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.8,BYTE-LENGTH}
@diagram{BYTE-LENGTH Function,FN-BYTE-LENGTH,FN-BYTE-LENGTH,None}
@code{BYTE-LENGTH} returns the length --- in bytes --- of @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal).  This intrinsic function is identical to the @syntaxref{LENGTH-AN} function.  Note that the value returned by this function is not necessarily the number of @i{characters} comprising @var{string}, but rather the number of actual @i{bytes} required to store it.

For example, if @var{string} is encoded using a double-byte character set such as Unicode UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to character sets like @sc{ASCII} or @sc{EBCDIC}), then calling this function with a @var{string} argument whose @syntaxref{PICTURE} is @code{N(4)} would return a value of 8 rather than the value 4.

Contrast this with the @syntaxref{LENGTH} function.
@comment *********************************************************************
@comment ** 8.1.9 CHAR                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.9,CHAR}
@diagram{CHAR Function,FN-CHAR,FN-CHAR,None}
This function returns the character in the ordinal position specified by @var{integer} (a numeric integer literal or data item with a value of 1 or greater) from the @syntaxrefalt{COLLATING SEQUENCE,OBJECT-COMPUTER} being used by the program.

For example, if the program is using the (default) @sc{ASCII} character set, CHAR(34) returns the 34th character in the @sc{ASCII} character set --- an exclamation-point (@samp{!}).  If you are using this function to convert a numeric value to its corresponding @sc{ASCII} character, you must use an argument value one greater than the numeric value.

If an argument whose value is less than 1 or greater than 256 is specified, the character in the program collating sequence corresponding to a value of all zero bits is returned.

The following code is an alternative approach when you just wish to convert a number to its @sc{ASCII} equivalent:

@example
01  Char-Value.
    05 Numeric-Value        USAGE BINARY-CHAR.
@dots{}
    MOVE numeric-character-value TO Numeric-Value
@end example

The @code{Char-Value} item now has the corresponding @sc{ASCII} character value.
@comment *********************************************************************
@comment ** 8.1.10 COMBINED-DATETIME                                         **
@comment *********************************************************************
@page
@newsubsection{8.1.10,COMBINED-DATETIME}
@diagram{COMBINED-DATETIME Function,FN-COMBINED-DATETIME,FN-COMBINED-DATETIME,None}
This function returns a 12-digit numeric result, the first seven digits of which are the integer value of @var{days} argument (a numeric data item or literal) and the last five of which are the integer value of @var{seconds} argument (also a numeric data item or literal).

If @var{days} is less than 1 or greater than 3,067,671, or if @var{seconds} is less than 1 or greater than 86,400, a value of 0 is returned and a runtime error will result.

@var{days}
Must be in integer date form. For details, see Integer date form.
A value in integer date form is a positive integer that represents a number of days succeeding 31 December 1600, in the Gregorian calendar. It is based on a starting date of Monday, 1 January 1601 and integer date 1 represents Monday, 1 January 1601.

@var{seconds}
Must be in standard numeric time form. For details, see Standard numeric time form. A value in standard numeric time form is a numeric value
representing seconds past midnight.

The returned value is determined by arithmetic expression
Days-1 + (Seconds-2/100000).
The date occupies the integer part of the returned value and the time is
represented in the fractional part of the returned value.

Example
Given the integer date form value "143951", which represents the date 15 February 1995, and the standard numeric time form value "18867.812479168304", which represents the time "05:14:27.812479168304", the returned value would be exactly "143951.1886781247".

@comment *********************************************************************
@comment ** 8.1.11 CONCAT                                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.11,CONCAT}
@diagram{CONCAT Function,FN-CONCATENATE,FN-CONCATENATE,None}
This function concatenates the @var{argument-1}, @var{argument-2}, @dots{} (group items, @code{USAGE DISPLAY} elementary items and/or alphanumeric literals) together into a single string result.

If a numeric literal or @code{PIC 9} identifier is specified as an argument, decimal points, if any, will be removed and negative signs in @code{PIC S9} fields or numeric literals will be inserted as defined by the @syntaxref{SIGN IS} clause (or absence thereof) of the field.  Numeric literals are processed as if @code{SIGN IS TRAILING SEPARATE} were in effect.

@comment *********************************************************************
@comment ** 8.1.11 CONCATENATE                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.11,CONCATENATE}
@diagram{CONCATENATE Function,FN-CONCATENATE,FN-CONCATENATE,None}
This function concatenates the @var{string-1}, @var{string-2}, @dots{} (group items, @code{USAGE DISPLAY} elementary items and/or alphanumeric literals) together into a single string result.

If a numeric literal or @code{PIC 9} identifier is specified as an argument, decimal points, if any, will be removed and negative signs in @code{PIC S9} fields or numeric literals will be inserted as defined by the @syntaxref{SIGN IS} clause (or absence thereof) of the field.  Numeric literals are processed as if @code{SIGN IS TRAILING SEPARATE} were in effect.

CONCATENATE is a GnuCOBOL extention BUT also see the ISO standard CONCAT function.

@comment *********************************************************************
@comment ** 8.1.12 CONTENT-LENGTH                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.12,CONTENT-LENGTH}
@diagram{CONTENT-LENGTH Function,FN-CONTENT-LENGTH,FN-CONTENT-LENGTH,None}
Scans for a NUL byte delimiter of the data starting at address in given pointer, and returns the length. The NUL byte is not included in the count. An EC-DATA-PTR-NUL exception is set to exist if the pointer is NUL, and a zero length is returned.

Function CONTENT-LENGTH is a GnuCOBOL extention.
@verbatim

Example:

 01  ptr USAGE POINTER.
 01  str  PIC X(4)  VALUE z"abc".

     SET      ptr TO ADDESS OF str.
     DISPLAY  FUNCTION CONTENT-LENGTH (str).

 Will display 3.

@end verbatim
@comment *********************************************************************
@comment ** 8.1.13 CONTENT-OF                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.13,CONTENT-OF}
@diagram{CONTENT-OF Function,FN-CONTENT-OF,FN-CONTENT-OF,None}
Takes a pointer and optional length. Returns a character field of the data addressed by the pointer, either up to a NUL byte or to the given length.

The NUL byte is not included in the data when no optional length is given.
With an optional count, the character field can hold any content including NUL bytes,

An EC-DATA-PTR-NUL exception is set to exist if the pointer is NUL, and a zero length space is returned.

An EC-SIZE-TRANCATION is set if the resulting field would exceed character field limits and the data is truncated.

Reference modification is allowed on resulting field.

Function CONTENT-OF is a GnuCOBOL extention.

@comment *********************************************************************
@comment ** 8.1.14 COS                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.14,COS}
@diagram{COS Function,FN-COS,FN-COS,None}
The @code{COS} function determines and returns the trigonometric cosine of @var{angle} (a numeric literal or data item) supplied as an argument.

@var{angle} is assumed to be a value expressed in radians.  If you need to determine the cosine of an angle measured in degrees, you first need to convert that angle to radians as follows:

@example
COMPUTE @var{radians} = ( @var{degrees} * FUNCTION PI) / 180
@end example
@comment *********************************************************************
@comment ** 8.1.15 CURRENCY-SYMBOL                                          **
@comment *********************************************************************
@page
@newsubsection{8.1.15,CURRENCY-SYMBOL}
@diagram{CURRENCY-SYMBOL Function,FN-CURRENCY-SYMBOL,FN-CURRENCY-SYMBOL,None}
The @code{CURRENCY-SYMBOL} function returns the currency symbol character currently in effect for the locale under which your program is running.  On UNIX systems, your locale is established via the
@envvarruntimeref{LANG} environment variable.  On Windows, the Control Panel's "Regional and Language Options" define the locale.

Changing the currency symbol via the @syntaxref{SPECIAL-NAMES} paragraph's @code{CURRENCY SYMBOL} setting will @i{not} affect the value returned by this function.
@comment *********************************************************************
@comment ** 8.1.16 CURRENT-DATE                                             **
@comment *********************************************************************
@page
@newsubsection{8.1.16,CURRENT-DATE}
@diagram{CURRENT-DATE Function,FN-CURRENT-DATE,FN-CURRENT-DATE,None}
Returns the current date and time as the following 21-character structure:

@example
01  CURRENT-DATE-AND-TIME.
    05 CDT-Year                PIC 9(4).
    05 CDT-Month               PIC 9(2). *> 01-12
    05 CDT-Day                 PIC 9(2). *> 01-31
    05 CDT-Hour                PIC 9(2). *> 00-23
    05 CDT-Minutes             PIC 9(2). *> 00-59
    05 CDT-Seconds             PIC 9(2). *> 00-59
    05 CDT-Hundredths-Of-Secs  PIC 9(2). *> 00-99
    05 CDT-GMT-Diff-Hours      PIC S9(2)
                               SIGN LEADING SEPARATE.
    05 CDT-GMT-Diff-Minutes    PIC 9(2). *> 00 or 30
@end example

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.17 DATE-OF-INTEGER                                          **
@comment *********************************************************************
@page
@newsubsection{8.1.17,DATE-OF-INTEGER}
@diagram{DATE-OF-INTEGER Function,FN-DATE-OF-INTEGER,FN-DATE-OF-INTEGER,None}
This function returns a numeric calendar date in @i{yyyymmdd} (i.e. Gregorian) format.  The date is determined by adding the number of days specified as @var{integer} (a numeric integer data item or literal) to the date December 31, 1600.  For example, @code{DATE-OF-INTEGER(1)} returns 16010101 while @code{DATE-OF-INTEGER(150000)} returns 20110908.

A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0.
@comment *********************************************************************
@comment ** 8.1.18 DATE-TO-YYYYMMDD                                         **
@comment *********************************************************************
@page
@newsubsection{8.1.18,DATE-TO-YYYYMMDD}
@diagram{DATE-TO-YYYYMMDD Function,FN-DATE-TO-YYYYMMDD,FN-DATE-TO-YYYYMMDD,None}
You can use this function to convert the six-digit Gregorian date specified as @var{yymmdd} (a numeric integer data item or literal) to an eight-digit format (@i{yyyymmdd}).

The optional @var{yy-cutoff} (a numeric integer data item or literal) argument is the year cutoff used to delineate centuries; if the year component of the date meets or exceeds this cutoff value, the result will be 19yymmdd; if the year component of the date is less than the cutoff value, the result will be 20yymmdd.  The default cutoff value if no second argument is given will be 50.

The optional @var{yy-execution-time} argument (a numeric integer data item or literal)   The default execution time value if no third argument is given will be now equivalent to specifying @code{(FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4)))}.
@comment *********************************************************************
@comment ** 8.1.19 DAY-OF-INTEGER                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.19,DAY-OF-INTEGER}
@diagram{DAY-OF-INTEGER Function,FN-DAY-OF-INTEGER,FN-DAY-OF-INTEGER,None}
This function returns a calendar date in yyyyddd (i.e. Julian) format.  The date is determined by adding the number of days specified as integer (a numeric integer data item or literal) to December 31, 1600.  For example, @code{DAY-OF-INTEGER(1)} returns 1601001 while @code{DAY-OF-INTEGER(250000)} returns 2011251.

A value less than 1 or greater than 3067671 (9999/12/31) will return a result of 0.
@comment *********************************************************************
@comment ** 8.1.20 DAY-TO-YYYYDDD                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.20,DAY-TO-YYYYDDD}
@diagram{DAY-TO-YYYYDDD Function,FN-DAY-TO-YYYYDDD,FN-DAY-TO-YYYYDDD,None}
You can use this function to convert the five-digit Julian date specified as @var{yyddd} (a numeric integer data item or literal) to a seven-digit numeric Julian format (yyyyddd).

The optional @var{yy-cutoff} argument (a numeric integer data item or literal) is the year cutoff used to delineate centuries; if the year component of the date meets or exceeds this cutoff value, the result will be 19yyddd; if the year component of the date is less than the cutoff, the result will be 20yyddd.  The default cutoff value if no second argument is given will be 50.

The optional @var{yy-execution-time} argument (a numeric integer data item or literal)   The default execution time value if no third argument is given will be now equivalent to specifying (FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))).
@comment *********************************************************************
@comment ** 8.1.21 E                                                        **
@comment *********************************************************************
@page
@newsubsection{8.1.21,E}
@diagram{E Function,FN-E,FN-E,None}
This function returns the mathematical constant @i{E} (the base of natural logarithms).  The maximum precision with which this value may be returned is 2.7182818284590452353602874713526625.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.22 EXCEPTION-FILE                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.22,EXCEPTION-FILE}
@diagram{EXCEPTION-FILE Function,FN-EXCEPTION-FILE,FN-EXCEPTION-FILE,None}
This function returns I/O exception information from the most-recently executed input or output statement.  The information is returned as a 34-character string, where the first two characters are the two-digit file status value (@pxref{File Status Codes}) and the remaining 32 are the @var{file-name-1} specification from the file's @syntaxref{SELECT} statement.

The name returned after the file status information will be returned only if the returned file status value is not 00.

Since this function has no arguments, no parenthesis should be specified.

The documentation of the @subpgmref{CBL_ERROR_PROC} built-in subroutine illustrates the use of this function.
@comment *********************************************************************
@comment ** 8.1.23 EXCEPTION-LOCATION                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.23,EXCEPTION-LOCATION}
@diagram{EXCEPTION-LOCATION Function,FN-EXCEPTION-LOCATION,FN-EXCEPTION-LOCATION,None}
This function returns exception information from the most-recently failing statement.  The information is returned to a 1023 character string in one of the following formats, depending on the nature of the failure:
@itemize @bullet

@item
primary-entry-point-name; paragraph OF section; statement-number

@item
primary-entry-point-name; section; statement-number

@item
primary-entry-point-name; paragraph; statement-number

@item
primary-entry-point-name; statement-number
@end itemize

Since this function has no arguments, no parenthesis should be specified.

The program must be compiled with the
@switchidx{-debug},
@switchidx{-ftraceall} or
@switchidx{-g} for this function to return any meaningful information.

The documentation of the @subpgmref{CBL_ERROR_PROC} built-in subroutine illustrates the use of this function.
@comment *********************************************************************
@comment ** 8.1.24 EXCEPTION-STATEMENT                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.24,EXCEPTION-STATEMENT}
@diagram{EXCEPTION-STATEMENT Function,FN-EXCEPTION-STMT,FN-EXCEPTION-STMT,None}
This function returns the most-recent COBOL statement that generated an exception condition.

Since this function has no arguments, no parenthesis should be specified.

The program must be compiled with the
@switchidx{-debug},
@switchidx{-ftraceall} or
@switchidx{-g} for this function to return any meaningful information.

The documentation of the @subpgmref{CBL_ERROR_PROC} built-in subroutine illustrates the use of this function.
@comment *********************************************************************
@comment ** 8.1.25 EXCEPTION-STATUS                                         **
@comment *********************************************************************
@page
@newsubsection{8.1.25,EXCEPTION-STATUS}
@diagram{EXCEPTION-STATUS Function,FN-EXCEPTION-STATUS,FN-EXCEPTION-STATUS,None}
This function returns the error type (a text string --- see column 2 of the upcoming table for the possible values) from the most-recent COBOL statement that generated an exception condition.

Since this function has no arguments, no parenthesis should be specified.

The documentation of the @subpgmref{CBL_ERROR_PROC} built-in subroutine illustrates the use of this function.

The following are the error type strings, and their corresponding exception codes and descriptions.
@anchoridx{Error Exception Codes}@anchoridx{Error Type Strings}
@multitable @columnfractions .075 .35 .575
@headitem Code @tab Error Type @tab Description


@item @code{0101}
@tab @code{EC-ARGUMENT-FUNCTION} @tab Function argument error

@item @code{0202}
@tab @code{EC-BOUND-ODO} @tab @code{OCCURS @dots{} DEPENDING} ON data item out of bounds

@item @code{0204}
@tab @code{EC-BOUND-PTR} @tab Data-pointer contains an address that is out of bounds

@item @code{0205}
@tab @code{EC-BOUND-REF-MOD} @tab Reference modifier out of bounds

@item @code{0207}
@tab @code{EC-BOUND-SUBSCRIPT} @tab Subscript out of bounds

@item @code{0303}
@tab @code{EC-DATA-INCOMPATIBLE} @tab Incompatible data exception

@item @code{0500}
@tab @code{EC-I-O} @tab input-output exception

@item @code{0501}
@tab @code{EC-I-O-AT-END} @tab I-O status @code{1x}

@item @code{0502}
@tab @code{EC-I-O-EOP} @tab An end of page condition occurred

@item @code{0504}
@tab @code{EC-I-O-FILE-SHARING} @tab I-O status @code{6x}

@item @code{0505}
@tab @code{EC-I-O-IMP} @tab I-O status @code{9x}

@item @code{0506}
@tab @code{EC-I-O-INVALID-KEY} @tab I-O status @code{2x}

@item @code{0508}
@tab @code{EC-I-O-LOGIC-ERROR} @tab I-O status @code{4x}

@item @code{0509}
@tab @code{EC-I-O-PERMANENT-ERROR} @tab I-O status @code{3x}

@item @code{050A}
@tab @code{EC-I-O-RECORD-OPERATION} @tab I-O status @code{5x}

@item @code{0601}
@tab @code{EC-IMP-ACCEPT} @tab Implementation-defined accept condition

@item @code{0602}
@tab @code{EC-IMP-DISPLAY} @tab Implementation-defined display condition

@item @code{0A00}
@tab @code{EC-OVERFLOW} @tab Overflow condition

@item @code{0A02}
@tab @code{EC-OVERFLOW-STRING} @tab @code{STRING} overflow condition

@item @code{0A03}
@tab @code{EC-OVERFLOW-UNSTRING} @tab @code{UNSTRING} overflow condition

@item @code{0B05}
@tab @code{EC-PROGRAM-NOT-FOUND} @tab Called program not found

@item @code{0D03}
@tab @code{EC-RANGE-INSPECT-SIZE} @tab Size of replace item in inspect differs

@item @code{1000}
@tab @code{EC-SIZE} @tab Size error exception

@item @code{1004}
@tab @code{EC-SIZE-OVERFLOW} @tab Arithmetic overflow in calculation

@item @code{1005}
@tab @code{EC-SIZE-TRUNCATION} @tab Significant digits truncated in store

@item @code{1007}
@tab @code{EC-SIZE-ZERO-DIVIDE} @tab Division by zero

@item @code{1202}
@tab @code{EC-STORAGE-NOT-ALLOC} @tab The data-pointer specified in a @code{FREE} statement does not identify currently allocated storage

@item @code{1203}
@tab @code{EC-STORAGE-NOT-AVAIL} @tab The amount of storage requested by an @*@code{ALLOCATE} statement is not available
@end multitable
@comment *********************************************************************
@comment ** 8.1.26 EXP                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.26,EXP}
@diagram{EXP Function,FN-EXP,FN-EXP,None}
Computes and returns the value of the mathematical constant @i{e} raised to the power specified by @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.27 EXP10                                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.27,EXP10}
@diagram{EXP10 Function,FN-EXP10,FN-EXP10,None}
Computes and returns the value of 10 raised to the power specified by @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.28 FACTORIAL                                                **
@comment *********************************************************************
@page
@newsubsection{8.1.28,FACTORIAL}
@diagram{FACTORIAL Function,FN-FACTORIAL,FN-FACTORIAL,None}
This function computes and returns the factorial value of @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.29 FORMATTED-CURRENT-DATE                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.29,FORMATTED-CURRENT-DATE}
@diagram{FORMATTED-CURRENT-DATE Function,FN-FORMATTED-CURRENT-DATE,FN-FORMATTED-CURRENT-DATE,None}
@code{FORMATTED-CURRENT-DATE} returns the current date and time provided by the system at run-time, formatted according to date-and-time-format according to the argument type.

FUNCTION FORMATTED-CURRENT-DATE gives you exactly what you asked it to, including up to nanoseconds (8 decimal positions in the seconds) [but the system may only provide miliseconds, especially on older win32].

The function argument must be a national or alphanumeric literal and the content, a combined date and time format.

The returned value is formatted to the same form as @var{argument-1}.
@comment *********************************************************************
@comment ** 8.1.30 FORMATTED-DATE                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.30,FORMATTED-DATE}
@diagram{FORMATTED-DATE Function,FN-FORMATTED-DATE,FN-FORMATTED-DATE,None}
@code{FORMATTED-DATE} uses a format to convert a date in integer date form to a date in the requested format. The returned value will be in date format.

@var{argument-1} shall be a national or alphanumeric literal.

@var{argument-2} shall be a value in integer date form.

Example
Given the date format "YYYYMMDD" and the value "143951", which represents the date 15 February 1995, the returned value would be "19950215".

@comment *********************************************************************
@comment ** 8.1.31 FORMATTED-DATETIME                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.31,FORMATTED-DATETIME}
@diagram{FORMATTED-DATETIME Function,FN-FORMATTED-DATETIME,FN-FORMATTED-DATETIME,None}
@code{FORMATTED-DATETIME} uses a combined time and date form to convert and combine a date in integer form and a numeric time expressed as seconds past midnight in UTC. See Date and Time Formats for details.

@var{argument-1} shall be a national or alphanumeric literal.

@var{argument-2} shall be a value in integer date form.

@var{argument-3} shall be a value in standard numeric time form.

@var{argument-4} is an integer specifying the offset from UTC expressed in minutes. If specified but have a value equal or less than 1439.

Note: The offset value 1439 represents 23 hours 59 minutes which is one minutes less than a day.

@var{argument-4} must not be specified if the time portion in @var{argument-1} is neither a UTC nor an offset format.

The returned value is a representation of the date contained in @var{argument-2} combined with the time contained in @var{argument-3} according to the format in @var{argument-1}.

If the format in @var{argument-1} indicates that the returned value is to be expressed in UTC, the time portion of the returned value reflects the adjustment of the value in @var{argument-3} by the offset in @var{argument-4}.

If the format in @var{argument-1} indicates that the time is to be returned as an offset from UTC, the value in @var{argument-3} is reflected directly in the time portion of the returned value and the offset in @var{argument-4} is reflected directly in the offset portion of the returned value.

Example
If the first argument has the format "YYMMDDThhmmss.ss+hhmm", the second argument the value
"143951", the third argument the value "18867.812479168304", and the fourth argument the value
"+300", the returned value would be "19950215T05142781+0500".

@comment *********************************************************************
@comment ** 8.1.32 FORMATTED-TIME                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.32,FORMATTED-TIME}
@diagram{FORMATTED-TIME Function,FN-FORMATTED-TIME,FN-FORMATTED-TIME,None}
@code{FORMATTED-TIME} converts a value representing seconds past midnight formatted time of day with optional offset.

@var{argument-1} shall be a national or alphanumeric literal.

@var{argument-2} shall be a value in integer time form.

@var{argument-3} is an integer specifying the offset from UTC expressed in minutes. If specified but have a value equal or less than 1439.

Note: The offset value 1439 represents 23 hours 59 minutes which is one minutes less than a day.

@var{argument-3} must not be specified if the time portion in @var{argument-1} is neither a UTC nor an offset format.

Returned value :

Is a representation of the standard numeric time contained in @var{argument-2} according to the format in @var{argument-1}.

If the format in @var{argument-1} indicates that the returned value is to be expressed in UTC, the time portion of the returned value reflects the adjustment of the value in @var{argument-2} by the offset in @var{argument-3}.

If the format in @var{argument-1} indicates that the time is to be returned as an offset from UTC, the value in @var{argument-2} is reflected directly in the time portion of the returned value and the offset in @var{argument-3} is reflected directly in the offset portion of the returned value.

Example
If the first argument has the format "hhmmss.ss+hhmm", the second argument the value "18867.812479168304" which represents the local time, and the third argument the value "-300", which represents the five hours that Eastern Standard Time (EST) differs from UTC, the returned value would be "05142781-0500".

@comment *********************************************************************
@comment ** 8.1.33 FRACTION-PART                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.33,FRACTION-PART}
@diagram{FRACTION-PART Function,FN-FRACTION-PART,FN-FRACTION-PART,None}
This function returns that portion of @var{number} (a numeric data item or a numeric literal) that occurs to the right of the decimal point.  @code{FRACTION-PART(3.1415)}, for example, returns a value of 0.1415.  This function is equivalent to the expression:

@example
@var{number} -- FUNCTION INTEGER-PART(@var{number})

Example:
display "base - " FUNCTION FRACTION-PART(FLOATER).
Gives
base - 000.456789

@end example
@enumerate
@item
When moved to a variable, it MUST have a preceding 'V' in the PICTURE, i.e., PIC v(4).
@end enumerate
@comment ******************************************************************
@comment ** 8.1.34 HEX-OF                                               **
@comment ******************************************************************
@page
@newsubsection{8.1.34,HEX-OF}
@diagram{HEX-OF Function,FN-HEX-OF,FN-HEX-OF,None}
@code{HEX-OF} function returns an alphanumeric character string consisting of a hexadecimal representation of the argument used on input.
@enumerate
@item
The type of the function is alphanumeric.
@item
@var{argument-1} must be a data item, literal, or an intrinsic function result of any data class.
@end enumerate

@noindent
Returned values:
@enumerate
@item
An alphanumeric character string consisting of a hexadecimal representation of @var{argument-1}.
@item
The length of the character string returned, in bytes, is twice the length of @var{argument-1}, in bytes.
@end enumerate

@comment ******************************************************************
@comment ** 8.1.35 HEX-TO-CHAR                                          **
@comment ******************************************************************
@page
@newsubsection{8.1.35,HEX-TO-CHAR}
@diagram{HEX-TO-CHAR Function,FN-HEX-TO-CHAR,FN-HEX-TO-CHAR,None}
@code{HEX-TO-CHAR} function returns a character string that represents the hexadecimal digit characters supplied on input.
@enumerate
@item
The type of the function is alphanumeric.
@item
@var{argument-1} must be an alphanumeric literal, alphanumeric data item, or alphanumeric group item.
@item
@var{argument-1} must consist only of the characters '0' through '9', 'A' through 'F', and 'a' through 'f'.
@item
The length of @var{argument-1} must be a multiple of 2 bytes.
@end enumerate

@noindent
Returned values:
@enumerate
@item
A character string of bytes representing the hexadecimal digit characters of @var{argument-1}.
@item
The length of the result string is equal to the length of the input string divided by 2.
@end enumerate

@comment *********************************************************************
@comment ** 8.1.36 HIGHEST-ALGEBRAIC                                        **
@comment *********************************************************************
@page
@newsubsection{8.1.36,HIGHEST-ALGEBRAIC}
@diagram{HIGHEST-ALGEBRAIC Function,FN-HIGHEST-ALGEBRAIC,FN-HIGHEST-ALGEBRAIC,None}
This function returns the highest (i.e. largest or farthest away from 0 in a positive direction if @var{numeric-identifier} is signed) value that could possibly be stored in @var{numeric-identifier}.
@comment *********************************************************************
@comment ** 8.1.37 INTEGER                                                  **
@comment *********************************************************************
@page
@newsubsection{8.1.37,INTEGER}
@diagram{INTEGER Function,FN-INTEGER,FN-INTEGER,None}
The @code{INTEGER} function returns the greatest integer value that is less than or equal to @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.38 INTEGER-OF-DATE                                          **
@comment *********************************************************************
@page
@newsubsection{8.1.38,INTEGER-OF-DATE}
@diagram{INTEGER-OF-DATE Function,FN-INTEGER-OF-DATE,FN-INTEGER-OF-DATE,None}
This function converts @var{date} (a numeric integer data item or literal) --- presumed to be a Gregorian calendar form standard date (YYYYMMDD) --- to internal date form (the number of days that have transpired since 1600/12/31).

Once in that form, mathematical operations may be performed against the internal date before it is transformed back into a date using the @syntaxref{DATE-OF-INTEGER} or @syntaxref{DAY-OF-INTEGER} function.
@comment *********************************************************************
@comment ** 8.1.39 INTEGER-OF-DAY                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.39,INTEGER-OF-DAY}
@diagram{INTEGER-OF-DAY Function,FN-INTEGER-OF-DAY,FN-INTEGER-OF-DAY,None}
This function converts @var{date} (a numeric integer data item or literal) --- presumed to be a Julian calendar form standard date (YYYYDDD) --- to internal date form (the number of days that have transpired since 1600/12/31).

Once in that form, mathematical operations may be performed against the internal date before it is transformed back into a date using the @syntaxref{DATE-OF-INTEGER} or @syntaxref{DAY-OF-INTEGER} function.
@comment *********************************************************************
@comment ** 8.1.40 INTEGER-OF-FORMATTED-DATE                                **
@comment *********************************************************************
@page
@newsubsection{8.1.40,INTEGER-OF-FORMATTED-DATE}
@diagram{INTEGER-OF-FORMATTED-DATE Function,FN-INTEGER-OF-FORMATTED-DATE,FN-INTEGER-OF-FORMATTED-DATE,None}
@code{INTEGER-OF-FORMATTED-DATE} converts a date that is in specified format to integer date form.

@var{argument-1} shall be a national or alphanumeric literal. The content must be either a date format or a combined date and time format.

@var{argument-2} shall be a data item of the same type as @var{argument-1}.

If @var{argument-1} is a date format the content of @var{argument-2} shall be a valid date in that format.

If @var{argument-1} is a combined date and time format, the content of @var{argument-2} shall be a valid combined date and time in same format.
@comment *********************************************************************
@comment ** 8.1.41 INTEGER-PART                                             **
@comment *********************************************************************
@page
@newsubsection{8.1.41,INTEGER-PART}
@diagram{INTEGER-PART Function,FN-INTEGER-PART,FN-INTEGER-PART,None}
Returns the integer portion of @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.42 LENGTH                                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.42,LENGTH}
@diagram{LENGTH Function,FN-LENGTH,FN-LENGTH,None}
Returns the length --- in characters --- of @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal).

The value returned by this function is not the number of @i{bytes} of storage occupied by string, but rather the number of actual @i{characters} making up the string.  For example, if @var{string} is encoded using a double-byte character set such as Unicode UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to character sets like @sc{ASCII} or @sc{EBCDIC}), then calling this function with a @var{string} argument whose @code{PICTURE is X(4)} would return a value of 4 rather than the value 8 (the actual number of bytes of storage occupied by that item).

Contrast this function with the @syntaxref{BYTE-LENGTH} and @syntaxref{LENGTH-AN} functions.
@comment *********************************************************************
@comment ** 8.1.43 LENGTH-AN                                                **
@comment *********************************************************************
@page
@newsubsection{8.1.43,LENGTH-AN}
@diagram{LENGTH-AN Function,FN-LENGTH-AN,FN-LENGTH-AN,None}
This function returns the length --- in bytes of storage --- of @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal).

This intrinsic function is identical to the @syntaxref{BYTE-LENGTH} function.

Note that the value returned by this function is not the number of @i{characters} making up the @var{string}, but rather the number of actual @i{bytes} of storage required to store @var{string}.  For example, if @var{string} is encoded using a double-byte character set such as Unicode UTF-16 (where each character is represented by 16 bits of storage, not the 8-bits inherent to character sets like @sc{ASCII} or @sc{EBCDIC}), then calling this function with a @var{string} argument whose @code{PICTURE is N(4)} would return a value of 8 rather than the value 4.

Contrast this with the @syntaxref{LENGTH} function.
@comment *********************************************************************
@comment ** 8.1.44 LOCALE-COMPARE                                           **
@comment *********************************************************************
@page
@newsubsection{8.1.44,LOCALE-COMPARE}
@diagram{LOCALE-COMPARE Function,FN-LOCALE-COMPARE,FN-LOCALE-COMPARE,None}
The @code{LOCALE-COMPARE} function returns a character indicating the result of comparing @var{argument-1} and @var{argument-2} using a culturally-preferred ordering defined by a @var{locale}.

Either or both of the 1@sup{st} two arguments may be an alphanumeric literal, a group item or an elementary item appropriate to storing alphabetic or alphanumeric data.  If the lengths of the two arguments are unequal, the shorter will be assumed to be padded to the right with spaces.

The two arguments will be compared, character by character, against each other until their relationship to each other can be determined.  The comparison is made according to the cultural rules in effect for @var{locale} name or for the current locale if no @var{locale} argument is specified.  Once that relationship is determined, a one-character alphanumeric value will be returned as follows:
@itemize

@item
@samp{<} --- If @var{argument-1} is determined to be less than @var{argument-2}

@item
@samp{=} --- If the two arguments are equal to each other

@item
@samp{>} --- If @var{argument-1} is determined to be greater than @var{argument-2}
@end itemize

@xref{LOCALE Names}, for a list of typically-available locale names.
@comment *********************************************************************
@comment ** 8.1.45 LOCALE-DATE                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.45,LOCALE-DATE}
@diagram{LOCALE-DATE Function,FN-LOCALE-DATE,FN-LOCALE-DATE,None}
Converts the eight-digit Gregorian @var{date} (a numeric integer data item or literal) from yyyymmdd format to the format appropriate to the current locale.  On a Windows system, this will be the ``short date'' format as set using Control Panel.

You may include an optional second argument to specify the @var{locale} name (group item or @code{PIC X} identifier) you'd like to use for date formatting.  If used, this second argument @i{must} be an identifier.  Locale names are specified using UNIX-standard names.
@comment *********************************************************************
@comment ** 8.1.46 LOCALE-TIME                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.46,LOCALE-TIME}
@diagram{LOCALE-TIME Function,FN-LOCALE-TIME,FN-LOCALE-TIME,None}
Converts the four- (hhmm) or six-digit (hhmmss) @var{time} (a numeric integer data item or literal) to a format appropriate to the current locale.  On a Windows system, this will be the ``time'' format as set using Control Panel.

You may include an optional @var{locale} name (a group item or @code{PIC X} identifier) you'd like to use for time formatting.  If used, this second argument @i{must} be an identifier.  Locale names are specified using UNIX-standard names.
@comment *********************************************************************
@comment ** 8.1.47 LOCALE-TIME-FROM-SECONDS                                 **
@comment *********************************************************************
@page
@newsubsection{8.1.47,LOCALE-TIME-FROM-SECONDS}
@diagram{LOCALE-TIME-FROM-SECONDS Function,FN-LOC-TM-FROM-SECS,FN-LOC-TM-FROM-SECS,None}
Converts the number of @var{seconds} since midnight (a numeric integer data item or literal) to a format appropriate to the current locale.  On a Windows system, this will be the ``time'' format as set using Control Panel.

You may include an optional @var{locale} name (a group item or @code{PIC X} identifier) you'd like to use for time formatting.  If used, this second argument @i{must} be an identifier.  Locale names are specified using UNIX-standard names.

@xref{LOCALE Names}, for a list of typically-available locale names.
@comment *********************************************************************
@comment ** 8.1.48 LOG                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.48,LOG}
@diagram{LOG Function,FN-LOG,FN-LOG,None}
Computes and returns the natural logarithm (base @i{e}) of @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.49 LOG10                                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.49,LOG10}
@diagram{LOG10 Function,FN-LOG10,FN-LOG10,None}
Computes and returns the base 10 logarithm of @var{number} (a numeric literal or data item).
@comment *********************************************************************
@comment ** 8.1.50 LOWER-CASE                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.50,LOWER-CASE}
@diagram{LOWER-CASE Function,FN-LOWER-CASE,FN-LOWER-CASE,None}
This function returns the value of @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal), converted entirely to lower case.

What constitutes a ``letter'' (or upper/lower case too, for that manner) may be influenced through the use of a @syntaxrefalt{CHARACTER CLASSIFICATION,OBJECT-COMPUTER}.
@comment *********************************************************************
@comment ** 8.1.51 LOWEST-ALGEBRAIC                                         **
@comment *********************************************************************
@page
@newsubsection{8.1.51,LOWEST-ALGEBRAIC}
@diagram{LOWEST-ALGEBRAIC Function,FN-LOWEST-ALGEBRAIC,FN-LOWEST-ALGEBRAIC,None}
This function returns the lowest (i.e. smallest or farthest away from 0 in a negative direction if @var{numeric-identifier} is signed) value that could possibly be stored in @var{numeric-identifier}.
@comment *********************************************************************
@comment ** 8.1.52 MAX                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.52,MAX}
@diagram{MAX Function,FN-MAX,FN-MAX,None}
This function returns the maximum value from the specified list of numbers (each @var{number-n} may be a numeric data item or a numeric literal).
@comment *********************************************************************
@comment ** 8.1.53 MEAN                                                     **
@comment *********************************************************************
@page
@newsubsection{8.1.53,MEAN}
@diagram{MEAN Function,FN-MEAN,FN-MEAN,None}
This function returns the statistical mean value of the specified list of numbers (each @var{number-n} may be a numeric data item or a numeric literal).
@comment *********************************************************************
@comment ** 8.1.54 MEDIAN                                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.54,MEDIAN}
@diagram{MEDIAN Function,FN-MEDIAN,FN-MEDIAN,None}
This function returns the statistical median value of the specified list of numbers (each @var{number-n} may be a numeric data item or a numeric literal).
@comment *********************************************************************
@comment ** 8.1.55 MIDRANGE                                                 **
@comment *********************************************************************
@page
@newsubsection{8.1.55,MIDRANGE}
@diagram{MIDRANGE Function,FN-MIDRANGE,FN-MIDRANGE,None}
The @code{MIDRANGE} (middle range) function returns a numeric value that is the arithmetic mean (average) of the values of the minimum and maximum numbers from the supplied list.  Each @var{number-n} may be a numeric data items or a numeric literal.
@comment *********************************************************************
@comment ** 8.1.56 MIN                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.56,MIN}
@diagram{MIN Function,FN-MIN,FN-MIN,None}
This function returns the minimum value from the specified list of numbers (each @var{number-n} may be a numeric data item or a numeric literal).
@comment *********************************************************************
@comment ** 8.1.57 MOD                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.57,MOD}
@diagram{MOD Function,FN-MOD,FN-MOD,None}
This function returns the value of @var{value} modulo @var{modulus} (essentially the remainder from the division of @var{value} by @var{modulus}).  Both arguments may be numeric data items or numeric literals.  Either (or both) may have a non-integer value.
@comment *********************************************************************
@comment ** 8.1.58 MODULE-CALLER-ID                                         **
@comment *********************************************************************
@page
@newsubsection{8.1.58,MODULE-CALLER-ID}
@diagram{MODULE-CALLER-ID Function,FN-MODULE-CALLER-ID,FN-MODULE-CALLER-ID,None}
This function returns the null string if it is executed within a main program.  When executed with a subprogram, it returns the entry-point name of the program that called the subprogram.

The discussion of the @syntaxref{MODULE-TIME} function includes a sample program that uses this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.59 MODULE-DATE                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.59,MODULE-DATE}
@diagram{MODULE-DATE Function,FN-MODULE-DATE,FN-MODULE-DATE,None}
This function Returns the date the GnuCOBOL program that is executing the function was compiled, in the form yyyymmdd.

The discussion of the @syntaxref{MODULE-TIME} function includes a sample program that uses this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.60 MODULE-FORMATTED-DATE                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.60,MODULE-FORMATTED-DATE}
@diagram{MODULE-FORMATTED-DATE Function,FN-MODULE-FMTD-DATE,FN-MODULE-FMTD-DATE,None}
This function returns the fully-formatted date and time when the program executing the function was compiled.  The exact format of this returned string value may vary depending on the operating system and GnuCOBOL build type.

The discussion of the @syntaxref{MODULE-TIME} function includes a sample program that uses this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.61 MODULE-ID                                                **
@comment *********************************************************************
@page
@newsubsection{8.1.61,MODULE-ID}
@diagram{MODULE-ID Function,FN-MODULE-ID,FN-MODULE-ID,None}
This function returns the primary entry-point name (i.e. the @code{PROGRAM-ID} or @code{FUNCTION-ID} of the program.  @xref{IDENTIFICATION DIVISION}, for information on those clauses.

The discussion of the @syntaxref{MODULE-TIME} function includes a sample program that uses this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.62 MODULE-PATH                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.62,MODULE-PATH}
@diagram{MODULE-PATH Function,FN-MODULE-PATH,FN-MODULE-PATH,None}
This function returns the full path to the executable version of this GnuCOBOL program.  The filename component of this value will be exactly as typed on the command line, down to the use of upper- and lower-case letters and presence (or absence) of any extension.

The discussion of the @syntaxref{MODULE-TIME} function includes a sample program that uses this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.63 MODULE-SOURCE                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.63,MODULE-SOURCE}
@diagram{MODULE-SOURCE Function,FN-MODULE-SOURCE,FN-MODULE-SOURCE,None}
The filename of the source code of the program (as specified on the @command{cobc} command when the program was compiled) is returned by this function.

The discussion of the @syntaxref{MODULE-TIME} function includes a sample program that uses this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.64 MODULE-TIME                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.64,MODULE-TIME}
@diagram{MODULE-TIME Function,FN-MODULE-TIME,FN-MODULE-TIME,None}
This function returns the time the GnuCOBOL program was compiled, in the form hhmmss.

Since this function has no arguments, no parenthesis should be specified.

The following sample program uses all the MODULE- Functions:

@example
IDENTIFICATION DIVISION.
PROGRAM-ID. DEMOMODULE.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
    FUNCTION ALL INTRINSIC.
PROCEDURE DIVISION.
000-Main.
    DISPLAY "MODULE-CALLER-ID      = [" MODULE-CALLER-ID @samp{]}
    DISPLAY "MODULE-DATE           = [" MODULE-DATE @samp{]}
    DISPLAY "MODULE-FORMATTED-DATE = [" MODULE-FORMATTED-DATE @samp{]}
    DISPLAY "MODULE-ID             = [" MODULE-ID @samp{]}
    DISPLAY "MODULE-PATH           = [" MODULE-PATH @samp{]}
    DISPLAY "MODULE-SOURCE         = [" MODULE-SOURCE @samp{]}
    DISPLAY "MODULE-TIME           = [" MODULE-TIME @samp{]}
    STOP RUN
    .
@end example

The program produces this output when executed:

@example
MODULE-CALLER-ID = []
MODULE-DATE = [20180522]
MODULE-FORMATTED-DATE = [May 22 2018 12:43:14]
MODULE-ID = [DEMOMODULE]
MODULE-PATH = [/home/vince/cobolsrc/ACAS/demomodule]
MODULE-SOURCE = [demomodule.cbl]
MODULE-TIME = [124314]
@end example
@comment *********************************************************************
@comment ** 8.1.65 MONETARY-DECIMAL-POINT                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.65,MONETARY-DECIMAL-POINT}
@diagram{MONETARY-DECIMAL-POINT Function,FN-MON-DECIMAL-POINT,FN-MON-DECIMAL-POINT,None}
@code{MONETARY-DECIMAL-POINT} returns the character used to separate the integer portion from the fractional part of a monetary currency value according to the rules currently in effect for the locale under which your program is running.

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the
@envvarruntimeref{LANG} environment variable.  On Windows, the Control Panel's Regional and Language Options define the locale.

Using the @syntaxrefalt{DECIMAL-POINT IS COMMA,SPECIAL-NAMES} clause in your program will not affect the value returned by this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.66 MONETARY-THOUSANDS-SEPARATOR                             **
@comment *********************************************************************
@page
@newsubsection{8.1.66,MONETARY-THOUSANDS-SEPARATOR}
@diagram{MONETARY-THOUSANDS-SEPARATOR Function,FN-MON-THOUSANDS-SEP,FN-MON-THOUSANDS-SEP,None}
This function returns the character used to separate the thousands digit groupings of monetary currency values according to the rules currently in effect for the locale under which your program is running.

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the
@envvarruntimeref{LANG} environment variable.  On Windows, the Control Panel's Regional and Language Options define the locale.

Using the @syntaxrefalt{DECIMAL-POINT IS COMMA,SPECIAL-NAMES} clause in your program will not affect the value returned by this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.67 NUMERIC-DECIMAL-POINT                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.67,NUMERIC-DECIMAL-POINT}
@diagram{NUMERIC-DECIMAL-POINT Function,FN-NUM-DECIMAL-POINT,FN-NUM-DECIMAL-POINT,None}
This function returns the character used to separate the integer portion of a non-integer numeric item from the fractional part according to the rules currently in effect for the locale under which your program is running.

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the
@envvarruntimeref{LANG} environment variable.  On Windows, the Control Panel's Regional and Language Options define the locale.

Using the @syntaxrefalt{DECIMAL-POINT IS COMMA,SPECIAL-NAMES} clause in your program will not affect the value returned by this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.68 NUMERIC-THOUSANDS-SEPARATOR                              **
@comment *********************************************************************
@page
@newsubsection{8.1.68,NUMERIC-THOUSANDS-SEPARATOR}
@diagram{NUMERIC-THOUSANDS-SEPARATOR Function,FN-NUM-THOUSANDS-SEP,FN-NUM-THOUSANDS-SEP,None}
This function returns the character used to separate the thousands digit groupings of numeric values according to the rules currently in effect for the locale under which your program is running.

On UNIX (including OSX, Windows/Cygwin and Windows/MinGW) systems, your locale is established via the
@envvarruntimeref{LANG} environment variable.  On Windows, the Control Panel's Regional and Language Options define the locale.

Using the @syntaxrefalt{DECIMAL-POINT IS COMMA,SPECIAL-NAMES} clause in your program will not affect the value returned by this function.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.69 NUMVAL                                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.69,NUMVAL}
@diagram{NUMVAL Function,FN-NUMVAL,FN-NUMVAL,None}
The @code{NUMVAL} function converts a @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) to its corresponding numeric value.

The @var{string} must have any of the following formats, where '#' represents a sequence of one or more decimal digits:

@center # @ @ -# @ @ +# @ @ #- @ @ #+ @ @ #CR @ @ #DB

@center #.# @ @ -#.# @ @ +#.# @ @ #.#- @ @ #.#+ @ @ #.#CR @ @ #.#DB

There must be at least one digit character in the string.

Leading and/or trailing spaces are allowed, as are spaces before the first digit.

The character period in @var{argument-1} @var{string}, represents the decimal separator. The character comma in @var{argument-1} represents the grouping separator. When the @code{DECIMAL-POINT IS COMMA} clause is specified, the character comma shall be used in @var{argument-1} to represent the decimal separator and the character period shall be used to represent the grouping separator.

@i{Note}: Locale-based functionality equivalent to @code{NUMVAL} can be obtained by using the @code{NUMVAL-C} function with the @code{LOCALE} keyword. A currency sign is optional in @code{NUMVAL-C}. The locale category @code{LC_MONETARY} will be used because there is no sign convention specified in locale category @code{LC_NUMERIC}.

Returned values:

The returned value is the numeric value represented by @var{string}.

If it contains a @code{CR}, @code{DB}, or the minus sign (@samp{-}), the returned value is negative.

@comment *********************************************************************
@comment ** 8.1.70 NUMVAL-C                                                 **
@comment *********************************************************************
@page
@newsubsection{8.1.70,NUMVAL-C}
@diagram{NUMVAL-C Function,FN-NUMVAL-C,FN-NUMVAL-C,None}
This function converts a @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) representing a currency value to its corresponding numeric value.

The currency string if any, and any grouping separators preceding the decimal separator are ignored. Optionally, the currency string, sign convention, grouping separator and the decimal separator permitted in the character string may be specified by locale category @code{LC-MONETARY}, or the currency string may be specified by @var{symbol}.

The optional @var{symbol} character represents the currency symbol (a non-space single-character group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) that may be used as the currency character in @var{string}. Any spaces including leading or trailing are ignored. If no @var{symbol} is specified, the value that would be returned by the @intrinsicref{CURRENCY-SYMBOL} will be used.

If this references the @code{LOCALE} :

Changing the currency symbol via the @code{SPECIAL-NAMES} paragraph's @code{CURRENCY SYMBOL} setting will not affect the value returned by this function.

While @code{NUMVAL-C} will always use the currency symbol that is specified via the @code{SPECIAL-NAMES} paragraph's @code{CURRENCY SYMBOL} (or the system default which is currently always @samp{$}).

@var{string} may have any of the following formats, where '#' represents a sequence of one or more decimal digits and '$' represents the @var{symbol} character:

@center # @ @ -# @ @ +# @ @ #- @ @ #+ @ @ #CR @ @ #DB

@center #.# @ @ -#.# @ @ +#.# @ @ #.#- @ @ #.#+ @ @ #.#CR @ @ #.#DB

@center $# @ @ -$# @ @ +$# @ @ $#- @ @ $#+ @ @ $#CR @ @ $#DB

@center $#.# @ @ -$#.# @ @ +$#.# @ @ $#.#- @ @ $#.#+ @ @ $#.#CR @ @ $#.#DB

There must be at least one digit character in the string.

Leading and/or trailing spaces are allowed, as are spaces before and/or after the currency symbol, sign, CR and DB characters.

If the @code{ANYCASE} keyword is used the matching rules for detecting a currency string in @var{argument-1} are case-insensitive. If the @code{ANYCASE} keyword is not specified, the matching rules are case-sensitive.

If neither symbol nor the @code{LOCALE} keyword is specified, there shall be only one currency string used, either the default currency sign or a currency string specified in the @code{SPECIAL-NAMES} paragraph.

The returned value is the numeric value represented by string.

When the @code{LOCALE} keyword is specified, the returned value is negative if string contains a negative sign.

When the @code{LOCALE} keyword is not specified, the returning value is negative if string contains CR, DB, or a minus sign.
@comment *********************************************************************
@comment ** 8.1.70B NUMVAL-C                                                **
@comment *********************************************************************
@page
@newsubsection{8.1.70B,NUMVAL-C-2}
@diagram{NUMVAL-C Function,FN-NUMVAL-C-2,FN-NUMVAL-C-2,None}
This function
returns the numeric value represented by the character string specified by @var{argument-1} and defined as alphanumeric.

@var{argument-2}, the currency string if any, and any grouping separators preceding the decimal separator are ignored. Optionally, the currency string, sign convention, grouping separator and the decimal separator permitted in the character string may be specified by locale category @code{LC-MONETARY}, or the currency string may be specified by @var{argument-2}.

The optional alphanumeric @var{argument-2} character represents the currency symbol (a non-space and at least one single-character item, that may be used as the currency character in @var{argument-1}. Any spaces including leading or trailing are ignored. If no @var{argument-2} is specified, the value that would be returned by the @intrinsicref{CURRENCY-SYMBOL} will be used. @var{argument-2} must not contain any of the digits - through 9, characters @samp{*}, @samp{+}, @samp{-}, @samp{,} or @samp{.}; or the two consecutive letters @code{CR} or @code{DB}, whether upper or lower case or a combination of both.

@var{argument-2} specifies a currency string that may appear in @var{argument-1}.

If the @code{ANYCASE} keyword is specified, the matching rules for detecting a currency string in @var{argument-1} are case-insensitive. If not specified, the matching rules are case-sensitive.

If neither @var{argument-2} nor the @code{LOCALE} keyword is specified, there shall be only one currency string used, either the default currency sign or a currency string specified in the @code{SPECIAL-NAMES} paragraph.

While @code{NUMVAL-C} will always use the currency symbol that is specified via the @code{SPECIAL-NAMES} paragraph's @code{CURRENCY SYMBOL} (or the system default which is currently always '$') @var{argument-1} shall have any of the following formats, where '#' represents a sequence of one or more decimal digits and '$' represents the @var{symbol} character:

@center # @ @ -# @ @ +# @ @ #- @ @ #+ @ @ #CR @ @ #DB

@center #.# @ @ -#.# @ @ +#.# @ @ #.#- @ @ #.#+ @ @ #.#CR @ @ #.#DB

@center $# @ @ -$# @ @ +$# @ @ $#- @ @ $#+ @ @ $#CR @ @ $#DB

@center $#.# @ @ -$#.# @ @ +$#.# @ @ $#.#- @ @ $#.#+ @ @ $#.#CR @ @ $#.#DB

There must be at least one digit character in the string.

Leading and/or trailing spaces are allowed, as are spaces before and/or after the currency symbol, sign, CR and DB characters.

The returned value is the numeric value represented by @var{argument-1}.

When the @code{LOCALE} keyword is specified, the returned value is negative if string contains a negative sign and when not specified, the returning value is negative if string contains CR, DB, or a minus sign.
@comment *********************************************************************
@comment ** 8.1.71 NUMVAL-F                                                 **
@comment *********************************************************************
@page
@newsubsection{8.1.71,NUMVAL-F}
@diagram{NUMVAL-F Function,FN-NUMVAL-F,FN-NUMVAL-F,None}
This function converts a @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) representing a floating-point value to its corresponding numeric value.

@center # @ @ -# @ @ +# @ @ #E# @ @ -#E# @ @ +#E#

@center #E+# @ @ -#E+# @ @ +#E+# @ @ #E-# @ @ -#E-# @ @ +#E-#

@center #.# @ @ -#.# @ @ +#.# @ @ #.#E# @ @ -#.#E# @ @ +#.#E#

@center #.#E+# @ @ -#.#E+# @ @ +#.#E+# @ @ #.#E-# @ @ -#.#E-# @ @ +#.#E-#

There must be at least one digit character both before and after the @code{E} in the string.

Leading and/or trailing spaces are allowed, as are spaces before and/or after any sign characters.
@comment *********************************************************************
@comment ** 8.1.72 ORD                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.72,ORD}
@diagram{ORD Function,FN-ORD,FN-ORD,None}
This function returns the ordinal position in the program character set (usually @sc{ASCII}) corresponding to the 1@sup{st} character of @var{char} argument (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal).

For example, assuming the program is using the standard @sc{ASCII} collating sequence, @code{ORD('!')} returns 34 because @samp{!} is the 34th @sc{ASCII} character.  If you are using this function to convert an @sc{ASCII} character to its numeric value, you must subtract one from the result.

The following code is an alternative approach when you just wish to convert an @sc{ASCII} character to its numeric equivalent:

@example
01  Char-Value.
    05 Numeric-Value        USAGE BINARY-CHAR.
@dots{}
    MOVE "character" TO Char-Value
@end example

@code{Numeric-Value} now has the numeric value of @code{character}.
@comment *********************************************************************
@comment ** 8.1.73 ORD-MAX                                                  **
@comment *********************************************************************
@page
@newsubsection{8.1.73,ORD-MAX}
@diagram{ORD-MAX Function,FN-ORD-MAX,FN-ORD-MAX,None}
This function returns the ordinal position in the argument list corresponding to the @var{char-n} whose 1@sup{st} character has the highest position in the program collating sequence (usually @sc{ASCII}).

For example, assuming the program is using the standard @sc{ASCII} collating sequence, @code{ORD-MAX('Z', 'z', '!')} returns 2 because the 2nd character in the argument list (the @sc{ASCII} character @samp{z}) occurs after @samp{Z} and @samp{!} in the program collating sequence.  Each @var{char-n} argument may be a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal.
@comment *********************************************************************
@comment ** 8.1.74 ORD-MIN                                                  **
@comment *********************************************************************
@page
@newsubsection{8.1.74,ORD-MIN}
@diagram{ORD-MIN Function,FN-ORD-MIN,FN-ORD-MIN,None}
This function returns the ordinal position in the argument list corresponding to the @var{char-n} whose 1@sup{st} character has the lowest position in the program collating sequence (usually @sc{ASCII}).

For example, assuming the program is using the standard @sc{ASCII} collating sequence, @code{ORD-MIN('Z', 'z', '!')} returns 3 because the 3rd character in the argument list (the @sc{ASCII} character @samp{!}) occurs before @samp{Z} and @samp{z} in the program collating sequence.  Each @var{char-n} argument may be a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal.
@comment *********************************************************************
@comment ** 8.1.75 PI                                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.75,PI}
@diagram{PI Function,FN-PI,FN-PI,None}
This function returns the mathematical constant @i{PI}.  The maximum precision with which this value may be returned is 3.1415926535897932384626433832795029.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.76 PRESENT-VALUE                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.76,PRESENT-VALUE}
@diagram{PRESENT-VALUE Function,FN-PRESENT-VALUE,FN-PRESENT-VALUE,None}
The @code{PRESENT-VALUE} function returns a value that approximates the present value of a series of future period-end amounts specified by the various @var{value-n} arguments at a discount rate specified by the @var{rate} argument.

All arguments are numeric data items and/or numeric literals.
@iftex

The following equation summarizes how present value is calculated, where @i{N} is the number of @var{value} arguments:
@tex
$$ presentvalue = \sum_{i=1}^N
\left (value_i
\over (1+rate)^i\right) $$
@end tex
@end iftex
@comment *********************************************************************
@comment ** 8.1.77 RANDOM                                                   **
@comment *********************************************************************
@page
@newsubsection{8.1.77,RANDOM}
@diagram{RANDOM Function,FN-RANDOM,FN-RANDOM,None}
This function returns a pseudo-random non-integer value in the range 0 to 1 (for example, 0.123456789).

The purpose of the optional @var{seed} argument, is to initialize the chain of pseudo-random numbers that will be returned by the function.  Not only will calls to this function using the same @var{seed} value return the same pseudo-random number, but so will all subsequent executions of the function without a @var{seed}.  This is actually a good thing when you are testing your program because you can rely on always receiving the same sequence of ``random'' numbers if you always start using the same @var{seed}.

The @var{seed} may be any form of literal or data item.  If @var{seed} is numeric, its numeric value will serve as the seed value.  If @var{seed} is alphanumeric, a value for it will be determined as if it were used as an argument to @syntaxref{NUMVAL}.

Take, for example, the following sample program:
@verbatim
    IDENTIFICATION DIVISION.
    PROGRAM-ID. DEMORANDOM.
    DATA DIVISION.
    WORKING-STORAGE SECTION.
    01  Pseudo-Random-Number        USAGE COMP-1.
    PROCEDURE DIVISION.
    000-Main.
        MOVE FUNCTION RANDOM(1) TO Pseudo-Random-Number
        DISPLAY Pseudo-Random-Number
        PERFORM 4 TIMES
            MOVE FUNCTION RANDOM    TO Pseudo-Random-Number
            DISPLAY Pseudo-Random-Number
        END-PERFORM
        STOP RUN
        .
@end verbatim

Every time this program is executed, it will produce the same output, because the same sequence of pseudo-random numbers will be generated:
@verbatim
    0.41
    0.18467
    0.63340002
    0.26499999
    0.19169
@end verbatim

It is worth mentioning that if the @i{first} execution of @code{RANDOM} in your program lacks a @var{seed} argument, the result will be exactly as if that execution were coded with a @var{seed} argument value of 1.

Once your program has been thoroughly tested, you'll want different sequences to be generated each time the program runs.  One possible way to accomplish this is to use a @var{seed} that is likely to be different every time the program is executed, as is likely to be the case if the first @code{MOVE} statement in the previous example were replaced by this:

@verbatim
    MOVE RANDOM(FUNCTION CURRENT-DATE(1:16))
      TO Pseudo-Random-Number
@end verbatim

The first 16 characters returned by the @syntaxref{CURRENT-DATE} function will be a number in the format @code{@var{YYYYMMDDhhmmssnn}}, where @code{@var{YYYYMMDD}} is the current calendar date and @code{@var{hhmmssnn}} is the current time of day to the one one-hundredth of a second.  Since two different executions of the program will never get identical @code{CURRENT-DATE} values (unless they are executed in extremely close time frames to one another), using those first sixteen characters as the @code{RANDOM} seed will guarantee that receiving a duplicate sequence of pseudo-random numbers in two different executions of the program will be @i{highly} unlikely.
@comment *********************************************************************
@comment ** 8.1.78 RANGE                                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.78,RANGE}
@diagram{RANGE Function,FN-RANGE,FN-RANGE,None}
The @code{RANGE} function returns a value that is equal to the value of the maximum @var{number-n} in the argument list minus the value of the minimum @var{number-n} argument.

All @var{number-n} arguments are numeric data items and/or numeric literals.
@comment *********************************************************************
@comment ** 8.1.79 REM                                                     **
@comment *********************************************************************
@page
@newsubsection{8.1.79,REM}
@diagram{REM Function,FN-REM,FN-REM,None}
This function returns a numeric value that is the remainder of @var{number} divided by @var{divisor}.  Both arguments must be numeric data items or numeric literals.
@comment *********************************************************************
@comment ** 8.1.80 REVERSE                                                  **
@comment *********************************************************************
@page
@newsubsection{8.1.80,REVERSE}
@diagram{REVERSE Function,FN-REVERSE,FN-REVERSE,None}
This function returns the byte-by-byte reversed value of @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal).
@comment *********************************************************************
@comment ** 8.1.81 SECONDS-FROM-FORMATTED-TIME                              **
@comment *********************************************************************
@page
@newsubsection{8.1.81,SECONDS-FROM-FORMATTED-TIME}
@diagram{SECONDS-FROM-FORMATTED-TIME Function,FN-SECS-FROM-FMTD-TM,FN-SECS-FROM-FMTD-TM,None}
This function decodes the string @var{time} --- whose value represents a formatted time --- and returns the total number of seconds that string represents.

The @var{time} string must contain hours, minutes and seconds.  The time argument may be specified as a group item, @code{USAGE DISPLAY} elementary item or an alphanumeric literal.

The @var{format} argument is a string (a group item, @code{USAGE DISPLAY} elementary item or an alphanumeric literal) documenting the format of @var{time} using @code{@var{hh}}, @code{@var{mm}} and @code{@var{ss}} to denote where the respective time information can be found.  Any other characters found in @var{format} represent character positions that will be ignored.  For example, a format of @code{hhmmss} indicates that @var{time} will be treated as a six-digit string value where the first two characters are the number of hours, the next two represent minutes and the last two represent seconds.  A @var{format} of @code{hh:mm:ss}, however, describes @var{time} as an eight-character string where characters 3 and 6 will be ignored.
@comment *********************************************************************
@comment ** 8.1.82 SECONDS-PAST-MIDNIGHT                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.82,SECONDS-PAST-MIDNIGHT}
@diagram{SECONDS-PAST-MIDNIGHT Function,FN-SECS-PAST-MIDNIGHT,FN-SECS-PAST-MIDNIGHT,None}
This function returns the current time of day expressed as the total number of elapsed seconds since midnight.

Since this function has no arguments, no parenthesis should be specified.
@comment *********************************************************************
@comment ** 8.1.83 SIGN                                                     **
@comment *********************************************************************
@page
@newsubsection{8.1.83,SIGN}
@diagram{SIGN Function,FN-SIGN,FN-SIGN,None}
The @code{SIGN} function returns a -1 if the value of @var{number} (a numeric literal or numeric data item) is negative, a zero if the value of @var{number} is exactly zero and a 1 if the value of @var{number} if greater than 0.
@comment *********************************************************************
@comment ** 8.1.84 SIN                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.84,SIN}
@diagram{SIN Function,FN-SIN,FN-SIN,None}
This function determines and returns the trigonometric sine of @var{angle} (a numeric literal or numeric data item).

The @var{angle} is assumed to be a value expressed in radians.  If you need to determine the sine of an angle measured in degrees, you first need to convert that angle to radians as follows:

@example
COMPUTE @var{radians} = ( @var{degrees} * FUNCTION PI) / 180
@end example
@comment *********************************************************************
@comment ** 8.1.85 SQRT                                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.85,SQRT}
@diagram{SQRT Function,FN-SQRT,FN-SQRT,None}
The @code{SQRT} function returns a numeric value that approximates the square root of @var{number} (a numeric data item or numeric literal with a non-negative value).

The following two statements produce identical results:

@example
01  Result           PIC 9(4).9(10).
@dots{}
    MOVE FUNCTION SQRT(15) TO Result
    COMPUTE Result = 15 ^ 0.5
@end example
@comment *********************************************************************
@comment ** 8.1.86 STANDARD-DEVIATION                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.86,STANDARD-DEVIATION}
@diagram{STANDARD-DEVIATION Function,FN-STANDARD-DEVIATION,FN-STANDARD-DEVIATION,None}
This function returns the statistical standard deviation of the list of @var{number-n} arguments (numeric data items or numeric literals).
@comment *********************************************************************
@comment ** 8.1.87 STORED-CHAR-LENGTH                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.87,STORED-CHAR-LENGTH}
@diagram{STORED-CHAR-LENGTH Function,FN-STORED-CHAR-LENGTH,FN-STORED-CHAR-LENGTH,None}
Returns the length --- in bytes --- of the specified @code{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal), minus the total number of trailing spaces, if any.
@comment *********************************************************************
@comment ** 8.1.88 SUBSTITUTE                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.88,SUBSTITUTE}
@diagram{SUBSTITUTE Function,FN-SUBSTITUTE,FN-SUBSTITUTE,None}
This function parses @var{string}, replacing all occurrences of @var{from-n} strings with the corresponding @var{to-n} strings.

The @var{from-n} strings must match sequences in @var{string} exactly with regard to value and case.

A @var{from-n} string does not have to be the same length as its corresponding @var{to-n} string.

All arguments are group items, @code{USAGE DISPLAY} elementary items or alphanumeric literals.

A null @var{to-n} string will be treated as a single space.

When using Variables in place of @var{string} attention to NOT wanting Leading or trailing spaces usage of function TRIM needs to be utilised as failure to do so will result in variables treated with any unwanted spaces leading and/or trailing, i.e.,
@verbatim

move     function SUBSTITUTE-CASE (WS-Dest-File-Path,
                    function TRIM (WS-Inbound-Path),
                    function TRIM (WS-Desc-Path))
                               to WS-Dest-File-Path
@end verbatim
@comment *********************************************************************
@comment ** 8.1.89 SUBSTITUTE-CASE                                          **
@comment *********************************************************************
@page
@newsubsection{8.1.89,SUBSTITUTE-CASE}
@diagram{SUBSTITUTE-CASE Function,FN-SUBSTITUTE-CASE,FN-SUBSTITUTE-CASE,None}
The @code{SUBSTITUTE-CASE} function operates the same as the @syntaxref{SUBSTITUTE} function, except that @var{from-n} string matching is performed without regard to case.

All arguments are group items, @code{USAGE DISPLAY} elementary items or alphanumeric literals.

When using Variables in place of @var{string} attention to NOT wanting Leading or trailing spaces usage of function TRIM needs to be utilised as failure to do so will result in variables treated with any unwanted spaces leading and/or trailing, i.e.,
@verbatim

move     function SUBSTITUTE-CASE (WS-Dest-File-Path,
                    function TRIM (WS-Inbound-Path),
                    function TRIM (WS-Desc-Path))
                               to WS-Dest-File-Path
@end verbatim

@comment *********************************************************************
@comment ** 8.1.90 SUM                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.90,SUM}
@diagram{SUM Function,FN-SUM,FN-SUM,None}
The @code{SUM} function returns a value that is the sum of @var{number-n} arguments (these may be numeric data items or numeric literals).
@comment *********************************************************************
@comment ** 8.1.91 TAN                                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.91,TAN}
@diagram{TAN Function,FN-TAN,FN-TAN,None}
This function determines and returns the trigonometric tangent of @var{angle} (a numeric literal or numeric data item).

The @var{angle} is assumed to be a value expressed in radians.  If you need to determine the tangent of an angle measured in degrees, you first need to convert that angle to radians as follows:

@example
COMPUTE @var{radians} = ( @var{degrees} * FUNCTION PI) / 180
@end example
@comment *********************************************************************
@comment ** 8.1.92 TEST-DATE-YYYYMMDD                                       **
@comment *********************************************************************
@page
@newsubsection{8.1.92,TEST-DATE-YYYYMMDD}
@diagram{TEST-DATE-YYYYMMDD Function,FN-TEST-DATE-YYYYMMDD,FN-TEST-DATE-YYYYMMDD,None}
This function determines if the supplied @var{date} argument (a numeric integer data item or literal) is a valid date.

A valid date is one of the form yyyymmdd in the range 1601/01/01 to 9999/12/31, with no more than the expected maximum number of days in the month, accounting for leap year.

If the @var{date} is valid, a 0 value is returned.  If it isn't, a value of 1, 2 or 3 is returned signalling the problem lies with the year, month or day, respectively.
@comment *********************************************************************
@comment ** 8.1.93 TEST-DAY-YYYYDDD                                         **
@comment *********************************************************************
@page
@newsubsection{8.1.93,TEST-DAY-YYYYDDD}
@diagram{TEST-DAY-YYYYDDD Function,FN-TEST-DAY-YYYYDDD,FN-TEST-DAY-YYYYDDD,None}
This function determines if the supplied @var{date} (a numeric integer data item or literal) is a valid date.

A valid date is one of the form @code{yyyyddd} in the range 1601001 to 9999365.  Leap year is accounted for in determining the maximum number of days in a year.

If the date is valid, a 0 value is returned.  If it isn't, a value of 1 or 2 is returned signalling the problem lies with the year or day, respectively.
@comment *********************************************************************
@comment ** 8.1.94 TEST-FORMATTED-DATETIME                                  **
@comment *********************************************************************
@page
@newsubsection{8.1.94,TEST-FORMATTED-DATETIME}
@diagram{TEST-FORMATTED-DATETIME Function,FN-TEST-FORMATTED-DATETIME,FN-TEST-FORMATTED-DATETIME,None}
@code{TEST-FORMATTED-DATETIME} tests whether a date literal representing a date, a time or a combined date and time is valid according to the specified format.

@var{argument-1} must a literal of type alphanumeric, UTF-8 or national, that contains a date, time or combined data time format. See Date and Time formats for details.

@var{argument-2} must be a data item of the same type as @var{argument-1}.

Returned value:

If no format or range problems occur during evaluation of @var{argument-2} according to the format in @var{argument-1}, the returned value is zero. Otherwise the returned value is the ordinal character position at which the first error in @var{argument-2} was detected.

Example

Using the following arguments, it will generates a return value of 5, as the fifth character of argument-2 ("4") contains an incorrect value for the first digit of the month representation.

FUNCTION TEST-FORMATTED-DATETIME("YYYYMMDD", "20124523")


@comment *********************************************************************
@comment ** 8.1.95 TEST-NUMVAL                                              **
@comment *********************************************************************
@page
@newsubsection{8.1.95,TEST-NUMVAL}
@diagram{TEST-NUMVAL Function,FN-TEST-NUMVAL,FN-TEST-NUMVAL,None}
The @code{TEST-NUMVAL} function evaluates @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) for being appropriate for use as the @var{string} argument to a @syntaxref{NUMVAL} function, returning to a integer a zero value if it is appropriate otherwise if one or more characters are in error, the position of the first character in error or the length of the field plus one for other cases such as all spaces.

Note that these errors include but are not limited to: argument (@var{string}) is zero length, contains only spaces or contains valid characters but is incomplete, such as the string @samp{+.}.
@comment *********************************************************************
@comment ** 8.1.96 TEST-NUMVAL-C                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.96,TEST-NUMVAL-C}
@diagram{TEST-NUMVAL-C Function,FN-TEST-NUMVAL-C,FN-TEST-NUMVAL-C,None}
This function evaluates @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) for being appropriate for use as the @var{string} argument to a @syntaxref{NUMVAL-C} function, returning to a integer a zero value if it is appropriate otherwise if one or more characters are in error, the position of the first character in error or the length of the field plus one for other cases such as all spaces.

Note that these errors include but are not limited to: argument (@var{string}) is zero length, contains only spaces or contains valid characters but is incomplete, such as the string @samp{+.}.

The optional @var{symbol} argument serves the same function --- and has the same default and possible values --- as the corresponding argument of the @code{NUMVAL-C} function.
@comment *********************************************************************
@comment ** 8.1.97 TEST-NUMVAL-F                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.97,TEST-NUMVAL-F}
@diagram{TEST-NUMVAL-F Function,FN-TEST-NUMVAL-F,FN-TEST-NUMVAL-F,None}
This function evaluates @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal) for being appropriate for use as the @var{string} argument to a @syntaxref{NUMVAL-F} function, returning to a integer a zero value if it is appropriate otherwise if one or more characters are in error, the position of the first character in error or the length of the field plus one for other cases such as all spaces.

Note that these errors include but are not limited to: argument (string) is zero length, contains only spaces or contains valid characters but is incomplete, such as the string @samp{+.}.
@comment *********************************************************************
@comment ** 8.1.98 TRIM                                                     **
@comment *********************************************************************
@page
@newsubsection{8.1.98,TRIM}
@diagram{TRIM Function,FN-TRIM,FN-TRIM,None}
This function removes
@syntaxidx{LEADING} or
@syntaxidx{TRAILING} spaces from @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal).

The second argument is specified as a keyword, not a quoted string or identifier.  If no second argument is specified, @i{both} leading and trailing spaces will be removed.  The case (upper, lower or mixed) of this argument is irrelevant.
@comment *********************************************************************
@comment ** 8.1.99 UPPER-CASE                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.99,UPPER-CASE}
@diagram{UPPER-CASE Function,FN-UPPER-CASE,FN-UPPER-CASE,None}
This function returns the value of @var{string} (a group item, @code{USAGE DISPLAY} elementary item or alphanumeric literal), converted entirely to upper case.

What constitutes a ``letter'' (or upper/lower case too, for that manner) may be influenced through the use of a @syntaxrefalt{CHARACTER CLASSIFICATION,OBJECT-COMPUTER}.
@comment *********************************************************************
@comment ** 8.1.100 VARIANCE                                                 **
@comment *********************************************************************
@page
@newsubsection{8.1.100,VARIANCE}
@diagram{VARIANCE Function,FN-VARIANCE,FN-VARIANCE,None}
This function returns the statistical variance of the specified list of @var{number-n} arguments (these may be numeric data items or numeric literals).
@comment *********************************************************************
@comment ** 8.1.101 WHEN-COMPILED                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.101,WHEN-COMPILED}
@diagram{WHEN-COMPILED Function,FN-WHEN-COMPILED,FN-WHEN-COMPILED,None}
The @code{WHEN-COMPILED} intrinsic function, not to be confused with the @syntaxrefalt{WHEN-COMPILED,Special Registers} special register, returns the date and time the program was compiled, in @sc{ASCII}.

Since this function has no arguments, no parenthesis should be specified.

Unlike the @code{WHEN-COMPILED} special register, which has an @sc{ASCII} value of the compilation date/time in the format @code{mm/dd/yyhh.mm.ss}, the @code{WHEN-COMPILED} intrinsic function returns the compilation date/time as an @sc{ASCII} string in the format @code{yyyymmddhhmmssnnooooo}, where @code{yyyymmdd} is the date, @code{hhmmss} is the time, @code{nn} is the hundredths of a second component of the compilation time, if available (or @code{00} if it isn't) and @code{ooooo} is the time zone offset from GMT.

If the @switch{-fintrinsics=WHEN-COMPILED} or @switch{-fintrinsics=ALL} is specified to the compiler or the @syntaxref{REPOSITORY} paragraph specifies either @code{FUNCTION WHEN-COMPILED INTRINSIC} or @code{FUNCTION ALL INTRINSIC}, then references to @code{WHEN-COMPILED} (without a leading @code{FUNCTION} keyword will always reference this intrinsic function and there will be no way to access the @code{WHEN-COMPILED} special register.
@comment *********************************************************************
@comment ** 8.1.102 YEAR-TO-YYYY                                             **
@comment *********************************************************************
@page
@newsubsection{8.1.102,YEAR-TO-YYYY}
@diagram{YEAR-TO-YYYY Function,FN-YEAR-TO-YYYY,FN-YEAR-TO-YYYY,None}
@code{YEAR-TO-YYYY} converts @var{yy} --- a two-digit year --- to a four-digit format (@code{yyyy}).

The optional @var{yy-cutoff} argument is the year cutoff used to delineate centuries; if @var{yy} meets or exceeds this cutoff value, the result will be 19yy; if @var{yy} is less than the cutoff, the result will be 20yy.  The default cutoff value if no second argument is given will be 50.

The optional @var{yy-execution-time} argument (a numeric integer data item or literal)   The default execution time value if no third argument is given will be now equivalent to specifying (FUNCTION NUMVAL (FUNCTION CURRENT-DATE (1:4))).

All arguments must be numeric data items or numeric literals.
@comment *********************************************************************
@comment ** 8.1.103 BOOLEAN-OF-INTEGER                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.103,BOOLEAN-OF-INTEGER}
@diagram{BOOLEAN-OF-INTEGER Function,FN-BOOLEAN-OF-INTEGER,FN-BOOLEAN-OF-INTEGER,NOT-YET-IMPLEMENTED}
@code{BOOLEAN-OF-INTEGER} returns a boolean item of usage bit representing the binary value of @var{argument-1}. @var{argument-2} specifies the length of the boolean data item that is returned.

@var{argument-1} must be a positive integer.

@var{argument-2} must be a positive non-zero integer

Returned value is a boolean item of usage bit that has the same bit configuration as the binary representation of the value of @var{argument-1}, where the rightmost boolean position is the low-order binary digit. The boolean value is zero-filled or truncated on the left, if necessary, in order to return a boolean item whose length is specified by @var{argument-2} in therms of boolean positions.
@comment *********************************************************************
@comment ** 8.1.104 CHAR-NATIONAL                                            **
@comment *********************************************************************
@page
@newsubsection{8.1.104,CHAR-NATIONAL}
@diagram{CHAR-NATIONAL Function,FN-CHAR-NATIONAL,FN-CHAR-NATIONAL,NOT-YET-IMPLEMENTED}
@code{CHAR-NATIONAL} returns a one character value that is a character in the national program collating sequence having the ordinal position equal to the value of the argument.

@var{argument-1} must be a integer and greater than zero and less than or equal to the number of positions in the national program collating sequence.
@comment *********************************************************************
@comment ** 8.1.105 DISPLAY-OF                                               **
@comment *********************************************************************
@page
@newsubsection{8.1.105,DISPLAY-OF}
@diagram{DISPLAY-OF Function,FN-DISPLAY-OF,FN-DISPLAY-OF,NOT-YET-IMPLEMENTED}
@code{DISPLAY-OF} returns a character string containing the alphabetic coded character set representation of the national characters in the argument.

@var{argument-1} must be of class national.

@var{argument-2} must be a of class alphabetic or alphanumeric and is one character position in length. It specifies an alphanumeric substitution character for use in conversion of national characters for which there is no corresponding alphanumeric character.

A character string is returned with each national character of @var{argument-1} converted to its corresponding alphanumeric character representation, if any.

If @var{argument-2} is specified, the alphanumeric substitution character is returned for each national character in @var{argument-1} that has no corresponding alphanumeric character representation.

If @var{argument-2} is un-specified, and @var{argument-1} contains a national character for which there is no corresponding alphanumeric character representation, an substitution character is used as the corresponding alphanumeric character and the EC-DATA-CONVERSION exception condition is set.

The length of the returned value is the number of character positions of usage display required to hold the converted argument and depends on the number of characters contained in @var{argument-1}.
@comment *********************************************************************
@comment ** 8.1.106 EXCEPTION-FILE-N                                        **
@comment *********************************************************************
@page
@newsubsection{8.1.106,EXCEPTION-FILE-N}
@diagram{EXCEPTION-FILE-N Function,FN-EXCEPTION-FILE-N,FN-EXCEPTION-FILE-N,NOT-YET-IMPLEMENTED}
@code{EXCEPTION-FILE-N} returns a national character string that is the I/O status value and file-name of the file connector, if any, associated with the last exception status.

The value returned has a length that is based on its contents and the concents are as follows:

If the last exception status is not an @code{EC-I-O} exception condition, the returned value is two national zeros.

The returned value is two national spaces when the last exception status indicates an @code{EC-I-O} exception condition that originates from one of the following statements:

@itemize @bullet
@item
a @code{RAISE} statement.

@item
an @code{EXIT} or a @code{GOBACK} statement with a @code{RAISING} phrase that specifies an @code{EC-I-O} exception-name.
@end itemize

@noindent
Otherwise the returned value is a character string that is as long as is needed to contain the I-O status value and the filename. The first two characters are the I-O status value in national characters. The succeeding characters contain the file-name exactly as specified in the @code{SELECT} clause converted at runtime to the runtime national character set.

The documentation of the @subpgmref{CBL_ERROR_PROC} built-in subroutine illustrates the use of this function.
@comment *********************************************************************
@comment ** 8.1.107 EXCEPTION-LOCATION-N                                    **
@comment *********************************************************************
@page
@newsubsection{8.1.107,EXCEPTION-LOCATION-N}
@diagram{EXCEPTION-LOCATION-N Function,FN-EXCEPTION-LOCATION-N,FN-EXCEPTION-LOCATION-N,NOT-YET-IMPLEMENTED}
@code{EXCEPTION-LOCATION-N} returns an national character string containing exception information from the most-recently failing statement.  The information is returned to a 1023 character string in one of the following formats, depending on the nature of the failure:
@itemize @bullet

@item
primary-entry-point-name; paragraph OF section; statement-number

@item
primary-entry-point-name; section; statement-number

@item
primary-entry-point-name; paragraph; statement-number

@item
primary-entry-point-name; statement-number
@end itemize

Since this function has no arguments, no parenthesis should be specified.

The program must be compiled with the
@switchidx{-debug},
@switchidx{-ftraceall} or
@switchidx{-g} for this function to return any meaningful information.

The documentation of the @subpgmref{CBL_ERROR_PROC} built-in subroutine illustrates the use of this function.
@comment *********************************************************************
@comment ** 8.1.108 INTEGER-OF-BOOLEAN                                      **
@comment *********************************************************************
@page
@newsubsection{8.1.108,INTEGER-OF-BOOLEAN}
@diagram{INTEGER-OF-BOOLEAN Function,FN-INTEGER-OF-BOOLEAN,FN-INTEGER-OF-BOOLEAN,NOT-YET-IMPLEMENTED}
@code{INTEGER-OF-BOOLEAN} returns the numeric value of the boolean string in @var{argument-1} which is class boolean.

Returned value as @var{argument-1} is assigned to a temporary boolean data item of usage bit described with the same number
of boolean positions.

The unsigned binary value represented by the same bit configuration as the bit configuration of that
temporary boolean data item is determined.

@i{Note}: Binary representation is a mathematical concept. It is not required that this representation be the same as a
COBOL representation.
@comment *********************************************************************
@comment ** 8.1.109 NATIONAL-OF                                             **
@comment *********************************************************************
@page
@newsubsection{8.1.109,NATIONAL-OF}
@diagram{NATIONAL-OF Function,FN-NATIONAL-OF,FN-NATIONAL-OF,NOT-YET-IMPLEMENTED}
@code{NATIONAL-OF} returns a character string containing the national character representation of the characters in the argument which must be of class boolean.

A character string is returned with each alphanumeric character in @var{argument-1} converted to its corresponding national coded character set representation.

If @var{argument-2} is specified, each character in @var{argument-1} that has no corresponding national representation is converted to the substitution character specified by @var{argument-2}.

If @var{argument-2} is unspecified and @var{argument-1} contains an alphanumeric character for which there is no corresponding national character representation, a substitution character is used as the corresponding national character and the @code{EC-DATA-CONVERSION} exception condition is set to exist.

The length of the returned value is the number of character positions of usage national required to hold the converted argument and depends on the number of characters contained in @var{argument-1}.
@comment *********************************************************************
@comment ** 8.1.110 STANDARD-COMPARE                                        **
@comment *********************************************************************
@page
@newsubsection{8.1.110,STANDARD-COMPARE}
@diagram{STANDARD-COMPARE Function,FN-STANDARD-COMPARE,FN-STANDARD-COMPARE,NOT-YET-IMPLEMENTED}
@code{STANDARD-COMPARE}  returns a character indicating the result of comparing @var{argument-1} as a alphanumeric and @var{argument-2} using a cultural ordering table.

@enumerate
@item
@var{argument-1} shall be of class alphabetic, alphanumeric, or national.

@item
@var{argument-2} shall be of class alphabetic, alphanumeric, or national.

@item
@var{argument-1} and @var{argument-2} may be of different classes.

@item
Neither @var{argument-1} nor @var{argument-2} shall be a zero-length literal.

@item
@var{ordering-name-1}, if specified, shall be associated with a cultural ordering table in the @code{ORDER TABLE} clause of the @code{SPECIAL-NAMES} paragraph. @var{ordering-name-1} identifies the ordering table to be used for the comparison. If @var{ordering-name-1} is not specified, the default ordering table `ISO14651_2010_TABLE1' described in Appendix A of ISO/IEC 14651:2011 shall be used.

@item
@var{argument-4}, if specified, shall be a positive nonzero integer.
@end enumerate

@noindent
Returned values:

@enumerate
@item
If @var{argument-4} is unspecified, the highest level defined in the ordering table is used for the comparison.

@item
If the cultural ordering table is not available on the processor, or the specified ordering level is not available, or the level number specified by @var{argument-4} is not defined in the ordering table, the @code{EC-ORDER-NOT-SUPPORTED} exception condition is set.

@item
If the arguments are of different classes, and one is national, the other argument is converted to class national for purposes of comparison.

@item
For purposes of comparison, trailing spaces are truncated from the operands except that an operand consisting of all spaces is truncated to a single space.

@item
@var{argument-1} and @var{argument-2} are compared in accordance with the ordering table and ordering level being used.

@i{Note}: This comparison is culturally sensitive and the default ordering table is acceptable for most cultures. It is not
necessarily a character-by-character comparison and not necessarily a case-sensitive comparison. In order to use this
function, users should understand the types of comparisons specified by ISO/IEC 14651:2D11 and the ordering tables in
use for their installation.

@page
@item
The returned value is:

@table @samp
@item =
the arguments compare equal,

@item -=.:
@var{argument-1} is less than @var{argument-2},

@item :>
@var{argument-1} is greater than @var{argument-2}.
@end table

@item
The length of the returned value is 1.
@end enumerate

@comment *********************************************************************
@comment ** 8.2 Built-In System Subroutines                                 **
@comment *********************************************************************
@page
@newsection{8.2,Built-In System Subroutines}
There are a number of built-in system subroutines included with GnuCOBOL.

Generally, these routines are intended to match those available in Micro Focus COBOL, ACUCOBOL and directly for GnuCOBOL.

It is recommended to change the CBL_OC routines to CBL_GC for forward compatibility as at some point they will be removed as they are a hangover from Open Cobol.

Prefix explanation:

@table @code
@item C$
--> @code{ACU}

@item CBL_
--> @code{MF}

@item CBL_GC_
(For backwards compatibility some routines are also available as @code{CBL_OC_}
as well): but these wonderful extensions are @i{only} available with GnuCOBOL.
@end table

These routines, all executed via their @i{upper-case names} via the @statementref{CALL}, are capable of performing the following functions:

@itemize @bullet
@item
Changing the current directory

@item
Copying files

@item
Creating a directory

@item
Creating, Opening, Closing, Reading and Writing byte-stream files

@item
Deleting directories (folders)

@item
Deleting files

@item
Determining how many arguments were passed to a subroutine

@item
Getting file information (size and last-modification date/time)

@item
Getting the length (in bytes) of an argument passed to a subroutine

@item
Justifying a field left-, right- or center-aligned

@item
Moving files (a destructive ``copy'')

@item
Putting the program ``to sleep'', specifying the sleep time in seconds

@item
Putting the program ``to sleep'', specifying the sleep time in nanoseconds; @i{Caveat}: although you'll express the time in nanoseconds, Windows systems will only be able to sleep at a millisecond granularity

@item
Retrieving information about the currently-executing program

@item
Submitting a command to the shell environment appropriate for the version of GnuCOBOL you are using for execution
@end itemize

Early versions of Micro Focus COBOL allowed programmers to access various runtime library routines by using a single two-digit hexadecimal number as the entry-point name.  These were known as call-by-number routines.  Over time, Micro Focus COBOL evolved, replacing most of the call-by-number routines with ones accessible using a more conventional call-by-name technique.

Most of the call-by-number routines have evolved into even more powerful call-by-name routines, many of which are supported by GnuCOBOL.

Some of the original call-by-number routines never evolved call-by-name equivalents; GnuCOBOL supports some of these routines.

The following sections describe the various built-in subroutines.  @i{All subroutine arguments are mandatory except where explicitly noted to the contrary}.  Any subroutine returning a value to the
@registerref{RETURN-CODE} could utilize the @code{RETURNING} clause on the
@statement{CALL} to return the result back to the full-word binary data item of your choice.
@menu
* 8.2.1:  C$CALLEDBY.
* 8.2.2:  C$CHDIR.
* 8.2.3:  C$COPY.
* 8.2.4:  C$DELETE.
* 8.2.5:  C$FILEINFO.
* 8.2.6:  C$GETPID.
* 8.2.7:  C$JUSTIFY.
* 8.2.8:  C$MAKEDIR.
* 8.2.9:  C$NARG.
* 8.2.10: C$PARAMSIZE.
* 8.2.11: C$PRINTABLE.
* 8.2.12: C$SLEEP.
* 8.2.13: C$TOLOWER.
* 8.2.14: C$TOUPPER.
* 8.2.15: CBL_AND.
* 8.2.16: CBL_CHANGE_DIR.
* 8.2.17: CBL_CHECK_FILE_EXIST.
* 8.2.18: CBL_CLOSE_FILE.
* 8.2.19: CBL_COPY_FILE.
* 8.2.20: CBL_CREATE_DIR.
* 8.2.21: CBL_CREATE_FILE.
* 8.2.22: CBL_DELETE_DIR.
* 8.2.23: CBL_DELETE_FILE.
* 8.2.24: CBL_EQ.
* 8.2.25: CBL_ERROR_PROC.
* 8.2.26: CBL_EXIT_PROC.
* 8.2.27: CBL_FLUSH_FILE.
* 8.2.28: CBL_GC_FORK.
* 8.2.29: CBL_GC_GETOPT.
* 8.2.30: CBL_GC_HOSTED.
* 8.2.31: CBL_GC_NANOSLEEP.
* 8.2.32: CBL_GC_PRINTABLE.
* 8.2.33: CBL_GC_WAITPID.
* 8.2.34: CBL_GET_CSR_POS.
* 8.2.35: CBL_GET_CURRENT_DIR.
* 8.2.36: CBL_GET_SCR_SIZE.
* 8.2.37: CBL_IMP.
* 8.2.38: CBL_NIMP.
* 8.2.39: CBL_NOR.
* 8.2.40: CBL_NOT.
* 8.2.42: CBL_OPEN_FILE.
* 8.2.43: CBL_OR.
* 8.2.44: CBL_READ_FILE.
* 8.2.45: CBL_READ_KBD_CHAR.
* 8.2.46: CBL_RENAME_FILE.
* 8.2.47: CBL_SET_CSR_POS.
* 8.2.48: CBL_SET_SCR_SIZE.
* 8.2.49: CBL_TOLOWER.
* 8.2.50: CBL_TOUPPER.
* 8.2.51: CBL_WRITE_FILE.
* 8.2.52: CBL_XOR.
* 8.2.53: SYSTEM.
* 8.2.54: X"91".
* 8.2.55: X"E4".
* 8.2.56: X"E5".
* 8.2.57: X"F4".
* 8.2.58: X"F5".
@end menu
@page
@comment *********************************************************************
@comment ** 8.2.1 C$CALLEDBY                                                **
@comment *********************************************************************
@newsubsection{8.2.1,C$CALLEDBY}
@diagram{C$CALLEDBY Built-In Subroutine,SS-C$CALLEDBY,SS-C$CALLEDBY,None}
This routine returns the name of the program that called the currently-executing program.  The program name will be returned, left-justified and space filled, in @var{prog-name-area} argument, which should be a @code{PIC X} elementary item or a group item.  If @var{prog-name-area} is too small to receive the entire program name, the program name value will be truncated (on the right) to fit.

The
@registerref{RETURN-CODE} will be set to one of the following values:
@multitable @columnfractions 0.05 0.95
@item -1
@tab An error occurred.  The @var{prog-name-area} contents will be unchanged.
@item 0
@tab The program calling @code{C$CALLEDBY} was not called by any other program (in other words, it is a main program).  The @var{prog-name-area} contents will be set entirely to spaces.
@item 1
@tab The program calling @code{C$CALLEDBY} was indeed called by another program, and that program's name has been saved in @var{prog-name-area}.
@end multitable
@comment *********************************************************************
@comment ** 8.2.2 C$CHDIR                                                   **
@comment *********************************************************************
@page
@newsubsection{8.2.2,C$CHDIR}
@diagram{C$CHDIR Built-In Subroutine,SS-C$CHDIR,SS-C$CHDIR,None}
This routine makes @var{directory-path} (an alphanumeric literal or identifier) the current directory.

The return code of the operation is returned both in the @var{result} argument (any non-edited numeric identifier) as well as in the
@registerref{RETURN-CODE}.   The return code of the operation will be either 0=Success or 128=failure.

The directory change remains in effect until the program terminates (in which the original current directory at the time the program was started will be automatically restored) or until another @code{C$CHDIR} or a @subpgmref{CBL_CHANGE_DIR} is executed.
@comment *********************************************************************
@comment ** 8.2.3 C$COPY                                                    **
@comment *********************************************************************
@page
@newsubsection{8.2.3,C$COPY}
@diagram{C$COPY Built-In Subroutine,SS-C$COPY,SS-C$COPY,None}
Use this subroutine to copy file @var{src-file-path} to @var{dest-file-path} as if it were done via the @command{cp} (Unix/OSX) or @code{COPY} (Windows) command.

Both file path arguments may be alphanumeric literals or identifiers.

The third argument is required, but is unused.

If the attempt to copy the file fails (for example, it or the destination directory doesn't exist), the
@registerref{RETURN-CODE} will be set to 128; on successful completion it will be set to 0.
@comment *********************************************************************
@comment ** 8.2.4 C$DELETE                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.4,C$DELETE}
@diagram{C$DELETE Built-In Subroutine,SS-C$DELETE,SS-C$DELETE,None}
This routine deletes the file specified by the @var{file-path} argument (an alphanumeric literal or identifier) just as if that were done using the @command{rm} (Unix/OSX) or @command{ERASE} (Windows) command.

The second argument is required, but is unused.

If the attempt to delete the file fails (for example, it doesn't exist), the
@registerref{RETURN-CODE} will be set to 128; on successful completion it will be set to 0.
@comment *********************************************************************
@comment ** 8.2.5 C$FILEINFO                                                **
@comment *********************************************************************
@page
@newsubsection{8.2.5,C$FILEINFO}
@diagram{C$FILEINFO Built-In Subroutine,SS-C$FILEINFO,SS-C$FILEINFO,None}
With this routine you may retrieve the size of the file specified as the @var{file-path} argument (an alphanumeric literal or identifier) and the date/time that file was last modified.  File size information may not be available in the particular GnuCOBOL build / Operating System combination you are using and may therefore always be returned as zero.  The information is returned to the @var{file-info} argument, which is defined as the following 16-byte area:

@example
01  File-Info.
    05 File-Size-In-Bytes  PIC 9(18) COMP.
    05 Mod-YYYYMMDD        PIC 9(8)  COMP. *> Modification Date
    05 Mod-HHMMSS00        PIC 9(8)  COMP. *> Modification Time
@end example

The last two decimal digits in the modification time will always be 00.

If the subroutine is successful, a value of 0 will be returned in the
@registerref{RETURN-CODE}.  Failure to retrieve the needed statistics on the file will cause a
@register{RETURN-CODE} value of 35 to be passed back.  Supplying less than two arguments will generate a 128
@register{RETURN-CODE} value.
@comment *********************************************************************
@comment ** 8.2.6 C$GETPID}                                                 **
@comment *********************************************************************
@page
@newsubsection{8.2.6,C$GETPID}
@diagram{C$GETPID Built-In Subroutine,SS-C$GETPID,SS-C$GETPID,None}
Use this subroutine to return the PID (process ID) of the executing GnuCOBOL program.  The PID value is returned into the
@registerref{RETURN-CODE}.

There are no arguments to this routine.
@comment *********************************************************************
@comment ** 8.2.7 C$JUSTIFY                                                 **
@comment *********************************************************************
@page
@newsubsection{8.2.7,C$JUSTIFY}
@diagram{C$JUSTIFY Built-In Subroutine,SS-C$JUSTIFY,SS-C$JUSTIFY,None}
Use @code{C$JUSTIFY} to left, right or center-justify an alphabetic, alphanumeric or numeric edited data-item.  The optional @var{justification-type} argument indicates the type of the justification to be performed.  Its value is interpreted as follows:
@table @samp
@item C
the value will be centered

@item R
the value will be right-justified, space-filled to the left

@item L
the value will be left-justified, space-filled to the right
@end table

@noindent
If it begins with anything else, or is absent, it will be treated as if it is present and begins with a capital @samp{R}
@comment *********************************************************************
@comment ** 8.2.8 C$MAKEDIR                                                 **
@comment *********************************************************************
@page
@newsubsection{8.2.8,C$MAKEDIR}
@diagram{C$MAKEDIR Built-In Subroutine,SS-C$MAKEDIR,SS-C$MAKEDIR,None}
With this routine you may create a new directory --- the name of which is supplied as the @var{dir-path} argument (an alphanumeric literal or identifier).

Only the lowest-level directory (last) in the specified path can be created --- all others must already exist.  This subroutine will @i{not} behave as a @code{mkdir -p} (Unix) or @code{mkdir /p} (Windows).

The @registerref{RETURN-CODE} will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
@comment *********************************************************************
@comment ** 8.2.9 C$NARG                                                    **
@comment *********************************************************************
@page
@newsubsection{8.2.9,C$NARG}
@diagram{C$NARG Built-In Subroutine,SS-C$NARG,SS-C$NARG,None}
This subroutine returns the number of arguments passed to the program that calls it back to in the numeric field @var{arg-count-result}.  When called from within a user-defined function, a value of one (1) is returned if any arguments were passed to the function or a zero (0) otherwise.

When called from a main program, the returned value will always be 0.
@comment *********************************************************************
@comment ** 8.2.10 C$PARAMSIZE                                              **
@comment *********************************************************************
@page
@newsubsection{8.2.10,C$PARAMSIZE}
@diagram{C$PARAMSIZE Built-In Subroutine,SS-C$PARAMSIZE,SS-C$PARAMSIZE,None}
This subroutine returns the size (in bytes) of the subroutine argument supplied using the @var{argument-number} parameter (a numeric literal or data item).

The size is returned in the
@registerref{RETURN-CODE}.

If the specified argument does not exist, or an invalid argument number is specified, a value of 0 is returned.
@comment *********************************************************************
@comment ** 8.2.11 C$PRINTABLE                                              **
@comment *********************************************************************
@page
@newsubsection{8.2.11,C$PRINTABLE}
@diagram{C$PRINTABLE Built-In Subroutine,SS-C$PRINTABLE,SS-C$PRINTABLE,None}
The @code{C$PRINTABLE} subroutine converts the contents of the data-item specified as the first argument to printable characters.  Those characters that are deemed printable (as defined by the character set used by @var{data-item}) will remain unchanged, while those that are NOT printable will be converted to the character specified as the second argument.

If no @var{char} argument is provided, a period (@samp{.}) will be used.

@i{Note}: CBL_GC_PRINTABLE replaces this although it is currently still supported for legacy reasons.
@comment *********************************************************************
@comment ** 8.2.12 C$SLEEP                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.12,C$SLEEP}
@diagram{C$SLEEP Built-In Subroutine,SS-C$SLEEP,SS-C$SLEEP,None}
@code{C$SLEEP} puts the program to sleep for the specified number of seconds and/or fractions of a second.  The @var{seconds-to-sleep} argument may be a numeric literal or data item.

Sleep times less than 1 will be interpreted as 0, subject to the speed of the CPU and the O/S (Operating System) used, as well as the timing of the generated C code, which can immediately returns control to the calling program without any sleep delay.

When using a variable argument defined as 9(n)v9(m) where n is maximum seconds in 7 days, i.e., (60 x 60 x 24 x 7) = 604,800 (seconds)  and m is at a point too fast for the CPU and O/S. In practice m should be 2 for a hundredth of a second but actual testing against the target CPU would be need.

The maximum time can be adjusted by the define MAX_SLEEP_TIME during compilation of the compiler [and no I do not know where it is in the codebase] e.g.:
@verbatim

/* maximum sleep time in seconds, currently 7 days */
#define MAX_SLEEP_TIME 3600*24*7

@end verbatim
@comment *********************************************************************
@comment ** 8.2.13 C$TOLOWER                                                **
@comment *********************************************************************
@page
@newsubsection{8.2.13,C$TOLOWER}
@diagram{C$TOLOWER Built-In Subroutine,SS-C$TOLOWER,SS-C$TOLOWER,None}
This routine will converts the @var{convert-length} (a numeric literal or data item) leading characters of @var{data-item} (an alphanumeric identifier) to lower-case.

The @var{convert-length} argument must be specified @syntaxrefalt{BY VALUE,CALL}.
Any characters in @var{data-item} after the @var{convert-length} point will remain unchanged.

If @var{convert-length} is negative or zero, no conversion will be performed.
@comment *********************************************************************
@comment ** 8.2.14 C$TOUPPER                                                **
@comment *********************************************************************
@page
@newsubsection{8.2.14,C$TOUPPER}
@diagram{C$TOUPPER Built-In Subroutine,SS-C$TOUPPER,SS-C$TOUPPER,None}
This routine will converts the @var{convert-length} (a numeric literal or data item) leading characters of @var{data-item} (an alphanumeric identifier) to upper-case.

The @var{convert-length} argument must be specified @syntaxrefalt{BY VALUE,CALL}.
Any characters in @var{data-item} after the @var{convert-length} point will remain unchanged.

If @var{convert-length} is negative or zero, no conversion will be performed.
@comment *********************************************************************
@comment ** 8.2.15 CBL_AND                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.15,CBL_AND}
@diagram{CBL_AND Built-In Subroutine,SS-CBL_AND,SS-CBL_AND,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      0
  0      1      0
  1      0      0
  1      1      1
@end verbatim
@tab This subroutine performs a bit-by-bit logical @code{AND} operation between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the @code{AND} process.
 @* @* The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.16 CBL_CHANGE_DIR                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.16,CBL_CHANGE_DIR}
@diagram{CBL_CHANGE_DIR Built-In Subroutine,SS-CBL_CHANGE_DIR,SS-CBL_CHANGE_DIR,None}
This routine makes @var{directory-path} (an alphanumeric literal or identifier) the current directory.

The return code of the operation, which will be either 0=Success or 128=failure, is returned in the
@registerref{RETURN-CODE}.

The directory change remains in effect until the program terminates (in which the original current directory at the time the program was started will be automatically restored) or until another @code{CBL_CHANGE_DIR} or a @subpgmref{C$CHDIR} is executed.
@comment *********************************************************************
@comment ** 8.2.17 CBL_CHECK_FILE_EXIST                                     **
@comment *********************************************************************
@page
@newsubsection{8.2.17,CBL_CHECK_FILE_EXIST}
@diagram{CBL_CHECK_FILE_EXIST Built-In Subroutine,SS-CBL_CHK_FILE_EX,SS-CBL_CHK_FILE_EX,None}
With this routine you may retrieve the size of the file specified as the @var{file-path} argument (an alphanumeric literal or identifier) and the date/time that file was last modified.  File size information may not be available in the particular GnuCOBOL build / Operating System combination you are using and may therefore always be returned as zero.

The information is returned to the @var{file-info} argument, which is defined as the following 16-byte area:

@example
01  file-info.
    05 File-Size-In-Bytes  PIC 9(18)  COMP.
    05 Mod-DD              PIC 9(2)   COMP.  *> Modification Date
    05 Mod-MO              PIC 9(2)   COMP.
    05 Mod-YYYY            PIC 9(4)   COMP.
    05 Mod-HH              PIC 9(2)   COMP.  *> Modification Time
    05 Mod-MM              PIC 9(2)   COMP.
    05 Mod-SS              PIC 9(2)   COMP.
    05 FILLER              PIC 9(2)   COMP.  *> Always 00
@end example

If the subroutine is successful, a value of 0 will be returned in the
@registerref{RETURN-CODE}.  Failure to retrieve the needed statistics on the file will cause a
@register{RETURN-CODE} value of 35 to be passed back.  Supplying less than two arguments will generate a 128
@register{RETURN-CODE} value.
@comment *********************************************************************
@comment ** 8.2.18 CBL_CLOSE_FILE                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.18,CBL_CLOSE_FILE}
@diagram{CBL_CLOSE_FILE Built-In Subroutine,SS-CBL_CLOSE_FILE,SS-CBL_CLOSE_FILE,None}
The @code{CBL_CLOSE_FILE} subroutine closes a byte stream file previously opened by either the @subpgmref{CBL_OPEN_FILE} or @subpgmref{CBL_CREATE_FILE} subroutines.

If the file defined by the @var{file-handle} argument (a @code{PIC X(4) USAGE COMP-X} data item) was opened for output, an implicit @subpgmref{CBL_FLUSH_FILE} will be performed before the file is closed.

If the subroutine is successful, a value of 0 will be returned in the
@registerref{RETURN-CODE}.  Failure will cause a
@register{RETURN-CODE} value of -1 to be passed back.
@comment *********************************************************************
@comment ** 8.2.19 CBL_COPY_FILE                                            **
@comment *********************************************************************
@page
@newsubsection{8.2.19,CBL_COPY_FILE}
@diagram{CBL_COPY_FILE Built-In Subroutine,SS-CBL_COPY_FILE,SS-CBL_COPY_FILE,None}
Use this subroutine to copy file @var{src-file-path} to @var{dest-file-path} as if it were done via the @command{cp} (Unix/OSX) or @code{COPY} (Windows) command.

Both arguments may be alphanumeric literals or identifiers.

If the attempt to copy the file fails (for example, it or the destination directory doesn't exist), the
@registerref{RETURN-CODE} will be set to 128; on successful completion it will be set to 0.
@comment *********************************************************************
@comment ** 8.2.20 CBL_CREATE_DIR                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.20,CBL_CREATE_DIR}
@diagram{CBL_CREATE_DIR Built-In Subroutine,SS-CBL_CREATE_DIR,SS-CBL_CREATE_DIR,None}
With this routine you may create a new directory --- the name of which is supplied as the @var{dir-path} argument (an alphanumeric literal or identifier).

Only the lowest-level directory (last) in the specified path can be created --- all others must already exist.  This subroutine will @i{not} behave as a @code{mkdir -p} (Unix) or @code{mkdir /p} (Windows).

The
@registerref{RETURN-CODE} will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
@comment *********************************************************************
@comment ** 8.2.21 CBL_CREATE_FILE                                          **
@comment *********************************************************************
@page
@newsubsection{8.2.21,CBL_CREATE_FILE}
@diagram{CBL_CREATE_FILE Built-In Subroutine,SS-CBL_CREATE_FILE,SS-CBL_CREATE_FILE,None}
The @code{CBL_CREATE_FILE} subroutine creates the new file specified using the file-path argument and opens it for output as a byte-stream file usable by @subpgmref{CBL_WRITE_FILE}.

Arguments 2, 3 and 4 should be coded as the constant values shown.  @code{CBL_CREATE_FILE} is actually a special-case of the @subpgmref{CBL_OPEN_FILE} routine --- see that routine for a description of the meanings of arguments 2, 3 and 4.

A @var{file-handle} (@code{PIC X(4) USAGE COMP-X)} will be returned, for use on any subsequent @subpgmref{CBL_WRITE_FILE} or @subpgmref{CBL_CLOSE_FILE} calls.

The success or failure of the subroutine will be reported back in the
@registerref{RETURN-CODE}, with a value of -1 indicating an invalid argument and a value of 0 indicating success.
@comment *********************************************************************
@comment ** 8.2.22 CBL_DELETE_DIR                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.22,CBL_DELETE_DIR}
@diagram{CBL_DELETE_DIR Built-In Subroutine,SS-CBL_DELETE_DIR,SS-CBL_DELETE_DIR,None}
This subroutine deletes an empty directory.

The only argument --- @var{dir-path} (an alphanumeric literal or identifier) --- is the name of the directory to be deleted.

Only the lowest-level directory (last) in the specified path will be deleted, and that directory must be empty to be deleted.

The @registerref{RETURN-CODE} will be set to the return code of the operation; the value will be either 0=Success or 128=failure.
@comment *********************************************************************
@comment ** 8.2.23 CBL_DELETE_FILE                                          **
@comment *********************************************************************
@page
@newsubsection{8.2.23,CBL_DELETE_FILE}
@diagram{CBL_DELETE_FILE Built-In Subroutine,SS-CBL_DELETE_FILE,SS-CBL_DELETE_FILE,None}
This routine deletes the file specified by the @var{file-path} argument (an alphanumeric literal or identifier) just as if that were done using the @command{rm} (Unix/OSX) or @code{ERASE} (Windows) command.

If the attempt to delete the file fails (for example, it doesn't exist), the
@registerref{RETURN-CODE} will be set to 128; on successful completion it will be set to 0.
@comment *********************************************************************
@comment ** 8.2.24 CBL_EQ                                                   **
@comment *********************************************************************
@page
@newsubsection{8.2.24,CBL_EQ}
@diagram{CBL_EQ Built-In Subroutine,SS-CBL_EQ,SS-CBL_EQ,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      1
  0      1      0
  1      0      0
  1      1      1
@end verbatim
@tab This subroutine performs a bit-by-bit comparison between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the EQ process.
 @* @*
 The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.25 CBL_ERROR_PROC                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.25,CBL_ERROR_PROC}
@diagram{CBL_ERROR_PROC Built-In Subroutine,SS-CBL_ERROR_PROC,SS-CBL_ERROR_PROC,None}
This routine registers a general error-handling routine.

The @var{function} argument must be a numeric literal or a 32-bit binary data item (@code{USAGE BINARY-LONG}, for example) with a value of 0 or 1.  A value of 0 means that you will be registering (``installing'') an error procedure while a value of 1 indicates you're de-registering (``uninstalling'') a previously-installed error procedure.

The @var{program-pointer} must be a data item with a @syntaxref{USAGE} of @code{PROGRAM-POINTER} containing the address of your error procedure.  This item should be given a value using the @statementref{SET Program-Pointer}.  If the error procedure is written in GnuCOBOL, it must be a subroutine, not a user-defined function.

A success (0) or failure (non-0) result will be passed back in the
@registerref{RETURN-CODE}.

A custom error procedure will trigger when a runtime error condition is encountered.  An error procedure may be registered by a main program or a subprogram, but regardless of from where it was registered, it applies to the overall program compilation group  and will trigger when a runtime error occurs anywhere in the executable program.  If the error procedure was defined by a subprogram, that program must be loaded at the time the error procedure is executed.

An error procedure may be used to take whatever actions might be warranted to display additional information or to gracefully close down work in progress, but it cannot @i{prevent} the termination of program execution; should the error procedure not issue its own @code{STOP RUN}, control will return back to the standard error routine when the error procedure exits.

The code within the handler will be executed and --- once the handler issues a @code{return}, if it was written in C, or an @statementrefalt{EXIT PROGRAM,EXIT} or @statement{GOBACK}, if it was written in GnuCOBOL, the system-standard error handling routine will be executed.

Only one user-defined error procedure may be in effect at any time.

The following is a sample GnuCOBOL program that registers an error procedure.  The output of that program is shown as well.  As as you can see, the error handler's messages appear followed by the standard GnuCOBOL message.

@example
1.     IDENTIFICATION DIVISION.
2.     PROGRAM-ID. DemoERRPROC.
3.     ENVIRONMENT DIVISION.
4.     DATA DIVISION.
5.     WORKING-STORAGE SECTION.
6.     01  Err-Proc-Address            USAGE PROGRAM-POINTER.
7.     PROCEDURE DIVISION.
8.     S1.
9.         DISPLAY 'Program is starting'
10.        SET Err-Proc-Address TO ENTRY 'ErrProc'
11.        CALL 'CBL_ERROR_PROC' USING 0, Err-Proc-Address
12.        CALL 'Tilt' *> THIS DOESN'T EXIST!!!!
13.        DISPLAY 'Program is stopping'
14.        STOP RUN
15.        .
16.    END PROGRAM DemoERRPROC.
17.
18.    IDENTIFICATION DIVISION.
19.    PROGRAM-ID. ErrProc.
20.    PROCEDURE DIVISION.
21.    000-Main.
22.        DISPLAY 'Error: ' FUNCTION EXCEPTION-LOCATION
23.        DISPLAY '       ' FUNCTION EXCEPTION-STATEMENT
24.        DISPLAY '       ' FUNCTION EXCEPTION-FILE
25.        DISPLAY '       ' FUNCTION EXCEPTION-STATUS
26.        DISPLAY '*** Returning to Standard Error Routine ***'
27.        EXIT PROGRAM
28.        .
29.    END PROGRAM ErrProc.
@end example

When executed, this sample program generates the following console output.

@example
E:\Programs\Demos>demoerrproc
Program is starting
Error: DemoERRPROC; S1; 12
       CALL
       00
       EC-PROGRAM-NOT-FOUND
*** Returning to Standard Error Routine ***
DEMOERRPROC.cbl: 27: libcob: Cannot find module 'Tilt'

E:\Programs\Demos>

@end example
@comment *********************************************************************
@comment ** 8.2.26 CBL_EXIT_PROC                                            **
@comment *********************************************************************
@page
@newsubsection{8.2.26,CBL_EXIT_PROC}
@diagram{CBL_EXIT_PROC Built-In Subroutine,SS-CBL_EXIT_PROC,SS-CBL_EXIT_PROC,None}
This routine registers a general exit-handling routine.

The @var{function} argument must be a numeric literal or a 32-bit binary data item (@code{USAGE BINARY-LONG}, for example) with a value of 0 or 1.  A value of 0 means that you will be registering (``installing'') an exit procedure while a value of 1 indicates you're deregistering (``uninstalling'') a previously-installed exit procedure.

The @var{program-pointer} must be a data item with a @syntaxref{USAGE} of @code{PROGRAM-POINTER} containing the address of your exit procedure.

A success (0) or failure (non-0) result will be passed back in the
@registerref{RETURN-CODE}.

An exit procedure, once registered, will trigger whenever a @statementrefalt{STOP RUN,STOP} or a @statementref{GOBACK} is executed anywhere in the program.  The exit procedure may execute whatever code is desired to undertake an orderly shut down of the program.  Once the exit procedure terminates by executing an @statementrefalt{EXIT PROGRAM,EXIT} or a @statement{GOBACK}, the system-standard program termination routine will be executed.

Only one user-defined exit procedure may be in effect at any time.

The following is a sample GnuCOBOL program that registers an exit procedure.  The output of that program is shown as well.

@example
IDENTIFICATION DIVISION.
PROGRAM-ID. demoexitproc.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  Exit-Proc-Address           USAGE PROGRAM-POINTER.
PROCEDURE DIVISION.
000-Register-Exit-Proc.
    SET Exit-Proc-Address TO ENTRY "ExitProc"
    CALL "CBL_EXIT_PROC" USING 0, Exit-Proc-Address
    IF RETURN-CODE NOT = 0
        DISPLAY 'Error: Could not register Exit Procedure'
    END-IF
    .
099-Now-Test-Exit-Proc.
    DISPLAY
        'Executing a STOP RUN...'
    END-DISPLAY
    GOBACK.
END PROGRAM demoexitproc.

IDENTIFICATION DIVISION.
PROGRAM-ID. ExitProc.
DATA DIVISION.
WORKING-STORAGE SECTION.
01  Display-Date                PIC XXXX/XX/XX.
01  Display-Time                PIC XX/XX/XX.
01  Now                         PIC X(8).
01  Today                       PIC X(8).
PROCEDURE DIVISION.
000-Main.
    DISPLAY '*** STOP RUN has been executed ***'
    ACCEPT Today FROM DATE YYYYMMDD
    ACCEPT Now   FROM TIME
    MOVE Today TO Display-Date
    MOVE Now   TO Display-Time
    INSPECT Display-Time REPLACING ALL '/' BY ':'
    DISPLAY '***    ' Display-Date '  ' Display-Time '    ***'
    GOBACK.
END PROGRAM ExitProc.

@end example
@comment *********************************************************************
@comment ** 8.2.27 CBL_FLUSH_FILE                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.27,CBL_FLUSH_FILE}
@diagram{CBL_FLUSH_FILE Built-In Subroutine,SS-CBL_FLUSH_FILE,SS-CBL_FLUSH_FILE,None}
In Micro Focus COBOL, calling this subroutine flushes any as-yet unwritten buffers for the (output) file whose file-handle is specified as the argument to disk.

This routine is non-functional in GnuCOBOL.  It exists only to provide compatibility for applications that may have been developed for Micro Focus COBOL.
@comment *********************************************************************
@comment ** 8.2.28 CBL_GC_FORK                                             **
@comment *********************************************************************
@page
@newsubsection{8.2.28,CBL_GC_FORK}
@diagram{CBL_GC_FORK Built-In Subroute,SS-CBL_GC_FORK,SS-CBL_GC_FORK,None}
CBL_GC_FORK allows you to fork the current COBOL process to a new one.

The current content of the process's storage (including LOCAL-STORAGE) will be identical, any file handles get invalid in the new process, positions and file and record locks are only available to the original process.

This system routine is not available on Windows (exception: GCC on Cygwin).

Parameters: none

Returns: @code{pid} (the child process gets '0' returned, the calling process gets the @code{pid} of the created child).

Negative values are returned for system dependant error codes and -1 if the function is not available on the current system.

@code{CBL_GC_FORK} allows you to fork the current COBOL process to a new one. The
current content of the process' storage (including @code{LOCAL-STORAGE}) will be
identical, any file handles get invalid in the new process, positions and
file / record locks are only available to the original process.
This system routine is not available on Windows (exception: @command{gcc} on Cygwin).
Parameters: none Returns: @code{pid} (the child process gets 0 returned, the calling
process gets the @code{pid} of the created children). Negative values are returned for
system dependant error codes and -1 if the function is not available on the
current system.

@example
 IDENTIFICATION DIVISION.
 PROGRAM-ID. prog.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  CHILD-PID      PIC S9(9) BINARY.
 01  WAIT-STS       PIC S9(9) BINARY.
 PROCEDURE DIVISION.
     CALL     "CBL_GC_FORK" RETURNING CHILD-PID END-CALL
     EVALUATE TRUE
              WHEN CHILD-PID = ZERO
                   PERFORM CHILD-CODE
              WHEN CHILD-PID > ZERO
                   PERFORM PARENT-CODE
              WHEN CHILD-PID = -1
                   DISPLAY 'CBL_GC_FORK is not available on the current'
                   ' system!'
                   PERFORM CHILD-CODE
                   MOVE 0 TO CHILD-PID
                   PERFORM PARENT-CODE
              WHEN OTHER
                   MULTIPLY -1 BY CHILD-PID END-MULTIPLY
                   DISPLAY 'CBL_GC_FORK returned system error: ' CHILD-PID
     END-EVALUATE
     STOP     RUN.
 CHILD-CODE.
     CALL     "C$SLEEP" USING 1 END-CALL
     DISPLAY  "Hello, I am the child"
     MOVE     2 TO RETURN-CODE.
 PARENT-CODE.
     DISPLAY  "Hello, I am the parent"
     CALL     "CBL_GC_WAITPID" USING CHILD-PID RETURNING WAIT-STS
     MOVE     0 TO RETURN-CODE
     EVALUATE TRUE
              WHEN WAIT-STS >= 0
                   DISPLAY 'Child ended with status: ' WAIT-STS
              WHEN WAIT-STS = -1
                   DISPLAY 'CBL_GC_WAITPID is not available on the '
                   'current system!'
              WHEN WAIT-STS < -1
                   MULTIPLY -1 BY WAIT-STS END-MULTIPLY
                   DISPLAY 'CBL_GC_WAITPID returned system error: ' WAIT-STS
     END-EVALUATE.

@end example
@comment *********************************************************************
@comment ** 8.2.29 CBL_GC_GETOPT                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.29,CBL_GC_GETOPT}
@diagram{CBL_GC_GETOPT Built-In Subroutine,SS-CBL_GC_GETOPT,SS-CBL_GC_GETOPT,None}
@code{CBL_GC_GETOPT} adapts the well-known option parser, @code{getopt}, to GnuCOBOL.

The usage of this system routine is described by the following example.

@example
 IDENTIFICATION DIVISION.
 PROGRAM-ID. PROG.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 78  SHORTOPTIONS VALUE "jkl".
 01  LONGOPTIONS.
     05 OPTIONRECORD OCCURS 2 TIMES.
        10  OPTIONNAME   PIC X(25).
        10  HAS-VALUE    PIC 9.
        10  VALPOINT     POINTER VALUE NULL.
        10  RETURN-VALUE PIC X(4).
 01  LONGIND             PIC 99.
 01  LONG-ONLY           PIC 9 VALUE 1.
 01  RETURN-CHAR         PIC X(4).
 01  OPT-VAL             PIC X(10).
 01  COUNTER             PIC 9 VALUE 0.
@end example

We first need to define the necessary fields for @code{getopt}'s @code{shortoptions}, @code{longoptions}, longoption index (@code{longind}), long-only-option (@code{long-only})
and also the fields for return values @code{return-char} and @code{opt-val} (arbitrary
size with trimming, see return codes).

The @code{shortoptions} are written down as an alphanumeric field (i.e., a string
with arbitrary size) as follows:

@example
"ab:c::d"
@end example

This means we want @code{getopt} to look for short options named @samp{a}, @samp{b}, @samp{c} or @samp{d}, require an option value for @samp{b}, and accept an optional one for @samp{c}.

The @code{longoptions} are defined as a table of records with @code{oname}, @code{has-value}, @code{valpoint} and @code{val}.@footnote{Say what? the discussion and code seem to have diverged.}

@code{oname} defines the name of a longoption.
@code{has-value} defines if an option value is demanded (@code{has-val = 1}), optional
(@code{has-val = 2}) or not required (@code{has-val = 0}).

@code{valpoint} is a pointer used to specify an address to save @code{getopt's} return
value to. The pointer is optional. If it is @code{NULL}, @code{getopt} returns a value
as usual. If you use the pointer it has to point to a @code{PIC X(4)} field.
The field val is a @code{PIC X(4)} character which is returned if the longoption
was recognized.

The longoption structure is immutable! You can only vary the number of
records.

Now we have the tools to run @code{CBL_GC_GETOPT} within the procedure division.

@example
PROCEDURE DIVISION.
     MOVE     "version" to OPTIONNAME (1).
     MOVE     0 TO HAS-VALUE (1).
     MOVE     @samp{V} TO RETURN-VALUE (1).
     MOVE     "verbose" TO OPTIONNAME (2).
     MOVE     0 TO HAS-VALUE (2).
     MOVE     @samp{V} TO RETURN-VALUE (2).
     PERFORM  WITH TEST AFTER UNTIL RETURN-CODE = -1
              CALL 'CBL_GC_GETOPT' USING
                  BY REFERENCE SHORTOPTIONS LONGOPTIONS LONGIND
                  BY VALUE LONG-ONLY
                  BY REFERENCE RETURN-CHAR OPT-VAL
              END-CALL
              DISPLAY RETURN-CHAR END-DISPLAY
              DISPLAY OPT-VAL END-DISPLAY
     END-PERFORM
     STOP RUN.
@end example

The example shows how we initialize all parameters and call the routine until
@code{CBL_GC_GETOPT} runs out of options and returns -1.

@noindent
@code{return-char} might contain the following
regular character if an option was recognized:

@table @code
@item ?
undefined or ambiguous option

@item 1
non-option (only if first byte of so is @samp{-})

@item 0
@code{valpoint != NULL} and we are writing the return value to the specified address

@item -1
no more options (or reach the first non-option if first byte of @code{shortoptions} is @samp{+})
@end table

@noindent
The return-codes of @code{CBL_GC_GETOPT} are:

@table @code
@item 1
a non-option (only if first byte of so is @samp{-})

@item 0
@code{valpoint != NULL} and we are writing the return value to the specified address

@item -1
no more options (or reach the first non-option if first byte of @code{shortoptions} is @samp{+})

@item 2
truncated option value in @code{opt-val} (because @code{opt-val} was too small)

@item 3
a regular answer from @code{getopt}
@end table
@comment *********************************************************************
@comment ** 8.2.30 CBL_GC_HOSTED                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.30,CBL_GC_HOSTED}
@diagram{CBL_GC_HOSTED Built-In Subroutine,SS-CBL_GC_HOSTED,SS-CBL_GC_HOSTED,None}

@code{CBL_GC_HOSTED} provides access to the following C hosted variables:
@table @code
@item argc
@code{binary-long by value}

@item argv
@code{pointer to char **}

@item stdin, stdout, stderr
@code{pointer}

@item errno
giving address of @code{errno} in pointer to @code{binary-long}, use @code{based} for more
@end table

Direct access and conditional access to the following variables:

@table @code
@item tzname
@code{pointer to pointer to array of two char pointer}s

@item timezone
C @code{long}, will be seconds west of UTC

@item daylight
C @code{int}, will be 1 during daylight savings
@end table

The system will need @code{HAVE TIMEZONE} defined for these to return anything meaningful.  Attempts made when they are not available will return 1 from @code{CBL GC HOSTED}.

It returns 0 when match, 1 on failure, case matters as does length, "arg"
won't match.

The usage of this system routine is described by the following example.

@example
IDENTIFICATION DIVISION.
 PROGRAM-ID. HOSTED.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  Argc        BINARY-LONG.
 01  Argv        POINTER.
 01  Stdin       POINTER.
 01  Stdout      POINTER.
 01  Stderr      POINTER.
 01  Errno       POINTER.
 01  Err         BINARY-LONG BASED.
 01  Domain      FLOAT-LONG VALUE 3.0.
 01  Tzname      POINTER.
 01  Tznames     POINTER BASED.
     05  Tzs     POINTER OCCURS 2.
 01  Timezone    BINARY-LONG.
 01  Daylight    BINARY-SHORT.
*>
 PROCEDURE DIVISION.
     call     "CBL_GC_HOSTED" using stdin "stdin"
     display  "stdin : " stdin
     call     "feof" using by value stdin
     display  "feof stdin : " return-code
     call     "CBL_GC_HOSTED" using stdout "stdout"
     display  "stdout : " stdout
     call     "fprintf" using by value stdout by content "Hello" & x"0a"
     call     "CBL_GC_HOSTED" using stderr "stderr"
     display  "stderr : " stderr
     call     "fprintf" using by value stderr by content "on err" & x"0a"
     call     "CBL_GC_HOSTED" using argc "argc"
     display  "argc : " argc
     call     "CBL_GC_HOSTED" using argv "argv"
     display  "argv : " argv
     call     "args" using by value argc argv
     call     "CBL_GC_HOSTED" using errno "errno"
     display  "&errno : " errno
     set      address of err to errno
     display  "errno : " err
     call     "acos" using by value domain
     display  "errno after acos(3.0): " err ", EDOM is 33"
     call     "CBL_GC_HOSTED" using argc "arg"
     display  "'arg' lookup : " return-code
     call     "CBL_GC_HOSTED" using null "argc"
     display  "null with argc : " return-code
     display  "argc is still : " argc
*> the following only returns zero if the system has HAVE_TIMEZONE set
     call     "CBL_GC_HOSTED" using daylight "daylight "
     display  "'timezone' lookup : " return-code
     if       return-code not = 0
              display "system doesn't has timezone"
     else
              display "timezone is : " timezone
              call "CBL_GC_HOSTED" using daylight "daylight "
              display "'daylight' lookup : " return-code
              display "daylight is : " daylight
              set environment "TZ" to "PST8PDT"
              call static "tzset" returning omitted on exception
                        continue end-call
              call "CBL_GC_HOSTED" using tzname "tzname"
              display "'tzname' lookup : " return-code
*> tzs(1) will point to z"PST" and tzs(2) to z"PDT"
              if   return-code equal 0 and tzname not equal null then
                   set address of tznames to tzname
                   if   tzs(1) not equal null then
                        display "tzs #1 : " tzs(1)
                   end-if
                   if   tzs(2) not equal null then
                        display "tzs #2 : " tzs(2)
                   end-if
              end-if
     end-if
     goback.
 end program hosted.
@end example

Note that the legacy name of this routine that starts with @code{CBL_OC} is deprecated, as is @code{NANOSLEEP} but will still work. It is recommended that all library routines names starting with @code{CBL_OC} are replaced with @code{CBL_GC} to minimise issues.
@comment *********************************************************************
@comment ** 8.2.31 CBL_GC_NANOSLEEP                                        **
@comment *********************************************************************
@page
@newsubsection{8.2.31,CBL_GC_NANOSLEEP}
@diagram{CBL_GC_NANOSLEEP Built-In Subroutine,SS-CBL_GC_NANOSLEEP,SS-CBL_GC_NANOSLEEP,None}
This subroutine puts the program to sleep for the specified number of nanoseconds.

The effective granularity of @var{nanoseconds-to-sleep} values will depend upon the granularity of the system clock your computer is using and the timing granularity of the operating system that computer is running.

For example, you will not expect to see any difference between values of 1, 100, 500 or 1000, but you should see a difference between values such as 250000000 and 500000000.

The @var{nanoseconds-to-sleep} argument is a numeric literal or data item.

There are one @i{billion} nanoseconds in a second, so if you wanted to put the program to sleep for 1/4 second you'd use a @var{nanoseconds-to-sleep} value of 250000000.

Note that the legacy name of this routine starts with ``CBL_OC'' is deprecated, as is @code{HOSTED}, but will still work. It is recommended that all library routines names starting with ``CBL_OC'' are replaced with ``CBL_GC'' to minimise issues.
@comment *********************************************************************
@comment ** 8.2.32 CBL_GC_PRINTABLE                                        **
@comment *********************************************************************
@page
@newsubsection{8.2.32,CBL_GC_PRINTABLE}
@diagram{CBL_GC_PRINTABLE Built-In Subroutine,SS-CBL_GC_PRINTABLE,SS-CBL_GC_PRINTABLE,None}
The @code{CBL_GC_PRINTABLE} subroutine converts the contents of the data-item specified as the first argument to printable characters.

Those characters that are deemed printable (as defined by the character set used by @var{data-item}) will remain unchanged, while those that are @i{not} printable will be converted to the character specified as the second argument.

If no @var{char} argument is provided, a period (@samp{.}) will be used.
@comment *********************************************************************
@comment ** 8.2.33 CBL_GC_WAITPID                                          **
@comment *********************************************************************
@page
@newsubsection{8.2.33,CBL_GC_WAITPID}
@diagram{CBL_GC_WAITPID Built-In Subroutine,SS-CBL_GC_WAITPID,SS-CBL_GC_WAITPID,None}

@code{CBL_GC_WAITPID} allows you to wait until another system process ended.

Additionally you can check the process's return code.

Parameters: none

Returns: function-status / child-status

Negative values are returned for system dependant error codes and -1 if the function is not available on the current system.

@example
CALL     "CBL_GC_WAITPID" USING CHILD-PID RETURNING WAIT-STS
MOVE     0 TO RETURN-CODE
DISPLAY  'CBL_GC_WAITPID ended with status: ' WAIT-STS
@end example
@comment *********************************************************************
@comment ** 8.2.34 CBL_GET_CSR_POS                                          **
@comment *********************************************************************
@page
@newsubsection{8.2.34,CBL_GET_CSR_POS}
@diagram{CBL_GET_CSR_POS Built-In Subroutine,SS-CBL_GET_CSR_POS,SS-CBL_GET_CSR_POS,None}
This subroutine will retrieve the current cursor location on the screen, returning a 2-byte value into the supplied @var{cursor-locn-buffer}.  The first byte of @var{cursor-locn-buffer} will receive the current line (row) location while the second receives the current column location.

The returned location data will be in binary form, and will be based upon starting values of 0, meaning that if the cursor is located at line 15, column 12 at the time this routine is called, a value of (14,11) will be returned.

The following is a typical @var{cursor-locn-buffer} definition:

@example
01  CURSOR-LOCN-BUFFER.
    05 CURSOR-LINE          USAGE BINARY-CHAR.
    05 CURSOR-COLUMN        USAGE BINARY-CHAR.
@end example

Values of 1 (Line) and 1 (column) will be returned if GnuCOBOL was not generated to include screen I/O.
@comment *********************************************************************
@comment ** 8.2.35 CBL_GET_CURRENT_DIR                                      **
@comment *********************************************************************
@page
@newsubsection{8.2.35,CBL_GET_CURRENT_DIR}
@diagram{CBL_GET_CURRENT_DIR Built-In Subroutine,SS-CBL_GET_CURR_DIR,SS-CBL_GET_CURR_DIR,None}
This retrieves the fully-qualified pathname of the current directory, saving up to @var{length} characters of that name into @var{buffer}.

The first argument is unused, but must be specified.  It must be specified @syntaxrefalt{BY VALUE,CALL}.

The @var{length} argument must be specified @code{BY VALUE}.
The @var{buffer} argument must be specified @code{BY REFERENCE}.

The value specified for the @var{length} argument (a numeric literal or data item) should not exceed the actual length of @var{buffer} argument.

If the value specified for the @var{length} argument is LESS THAN the actual length of @var{buffer} argument, the current directory path will be left-justified and space filled within the first @var{length} bytes of @var{buffer} --- any bytes in @var{buffer} after that point will be unchanged.

If the routine is successful, a value of 0 will be returned to the
@registerref{RETURN-CODE}.  If the routine failed because of a problem with an argument (such as a negative or 0 length), a value of 128 will result.  Finally, if the 1@sup{st} argument value is anything but zero, the routine will fail with a 129 value.
@comment *********************************************************************
@comment ** 8.2.36 CBL_GET_SCR_SIZE                                         **
@comment *********************************************************************
@page
@newsubsection{8.2.36,CBL_GET_SCR_SIZE}
@diagram{CBL_GET_SCR_SIZE Built-In Subroutine,SS-CBL_GET_SCR_SIZE,SS-CBL_GET_SCR_SIZE,None}
Use this subroutine to retrieve the current console screen size.

When the system is running in a windowed environment, this will be the sizing of the console window in which the program is executing.  When the system is not running a windowing environment, the physical console screen attributes will be returned.  In environments such as a Windows console window, where the logical size of the window may far exceed that of the physical console window, the size returned will be that of the physical console window.  Two one-byte values will be returned --- the first will be the current number of lines (rows) while the second will be the number of columns.

The returned size data will be in binary form.

The following are typical @var{no-of-lines} and @var{no-of-columns} definitions:

@example
01  NO-OF-LINES             USAGE BINARY-CHAR.
01  NO-OF-COLUMNS           USAGE BINARY-CHAR.
@end example

GnuCOBOL run-time screen management must have been initialized prior to CALLing this routine in order to receive meaningful values.  This means that a @statementref{DISPLAY data-item} or a @statementref{ACCEPT data-item} must have been executed prior to executing the @statement{CALL}.

Zero values will be returned if the screen has not been initialized and values of 24 (lines) and 80 (columns) will be returned if GnuCOBOL was not generated to include screen I/O.
@comment *********************************************************************
@comment ** 8.2.37 CBL_IMP                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.37,CBL_IMP}
@diagram{CBL_IMP Built-In Subroutine,SS-CBL_IMP,SS-CBL_IMP,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      1
  0      1      1
  1      0      0
  1      1      1
@end verbatim
@tab This subroutine performs a bit-by-bit logical @i{implies} process between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the @code{IMP} process.
 @* @* The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.38 CBL_NIMP                                                 **
@comment *********************************************************************
@page
@newsubsection{8.2.38,CBL_NIMP}
@diagram{CBL_NIMP Built-In Subroutine,SS-CBL_NIMP,SS-CBL_NIMP,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      0
  0      1      0
  1      0      1
  1      1      0
@end verbatim
@tab This subroutine performs the @i{negation} of a bit-by-bit logical @i{implies} process between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the @code{NIMP} process.
 @* @* The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.39 CBL_NOR                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.39,CBL_NOR}
@diagram{CBL_NOR Built-In Subroutine,SS-CBL_NOR,SS-CBL_NOR,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      1
  0      1      0
  1      0      0
  1      1      0
@end verbatim
@tab This subroutine performs the negation of a bit-by-bit logical @i{or'} process between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the @code{NOR} process.
 @* @* The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.40 CBL_NOT                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.40,CBL_NOT}
@diagram{CBL_NOT Built-In Subroutine,SS-CBL_NOT,SS-CBL_NOT,None}
This subroutine ``flips'' the left-most 8*@var{byte-length} bits of @var{item-1}, changing 0 bits to 1, and 1 bits to 0.  The changes are made directly im @var{item-1}.

The @var{item-1} argument must be a data item.  The length of @var{item-1} must be at least 8*@var{byte-length}.

The @var{byte-length} argument may be a numeric literal or data item, and must be passed using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-1} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.42 CBL_OPEN_FILE                                            **
@comment *********************************************************************
@page
@newsubsection{8.2.42,CBL_OPEN_FILE}
@diagram{CBL_OPEN_FILE Built-In Subroutine,SS-CBL_OPEN_FILE,SS-CBL_OPEN_FILE,None}
This routine opens an existing file for use as a byte-stream file usable by CBL_WRITE_FILE or CBL_READ_FILE.

The @var{file-path} argument  is an alphanumeric literal or data-item.

The @var{access-mode} argument is a numeric literal or data item with a @code{PIC X USAGE COMP-X} (or @code{USAGE BINARY-CHAR}) definition; it specifies how you wish to use the file, as follows:

@table @code
@item 1
input (read-only)

@item 2
output (write-only)

@item 3
input and/or output
@end table

The third and fourth arguments would specify a locking mode and device specification, respectively, but they're not implemented in GnuCOBOL (currently, at least) --- just specify each as 0.

The final argument (@var{handle}) is a @code{PIC X(4) USAGE COMP-X} item that will receive the handle to the file.  That handle is used on all other byte-stream functions to reference this specific file.

A
@registerref{RETURN-CODE} value of -1 indicates an invalid argument, while a value of 0 indicates success.  A value of 35 means the file does not exist.
@comment *********************************************************************
@comment ** 8.2.43 CBL_OR                                                   **
@comment *********************************************************************
@page
@newsubsection{8.2.43,CBL_OR}
@diagram{CBL_OR Built-In Subroutine,SS-CBL_OR,SS-CBL_OR,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      0
  0      1      1
  1      0      1
  1      1      1
@end verbatim
@tab This subroutine performs a bit-by-bit logical @i{or} process between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the @code{OR} process.
 @* @* The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.44 CBL_READ_FILE                                            **
@comment *********************************************************************
@page
@newsubsection{8.2.44,CBL_READ_FILE}
@diagram{CBL_READ_FILE Built-In Subroutine,SS-CBL_READ_FILE,SS-CBL_READ_FILE,None}
This routine reads @var{nbytes} of data starting at byte number @var{offset} from the byte-stream file defined by @var{handle} into @var{buffer}.

The @var{handle} argument (@code{PIC X(4) USAGE COMP-X}) must have been populated by a prior call to @subpgmref{CBL_OPEN_FILE}.

The @var{offset} argument (@code{PIC X(8) USAGE COMP-X}) defines the location in the file of the first byte to be read.  The first byte of a file is byte offset 0 and MUST be preset to zero for first use.

The @var{nbytes} argument (@code{PIC X(4) USAGE COMP-X}) specifies how many bytes (maximum) will be read.
If the @var{flag} argument is specified as 128, the size of the file (in bytes) will be returned into the file offset argument (argument 2) upon completion.  Not all operating system/GnuCOBOL environments may be able to retrieve file sizes  in such cases, a value of zero will be returned.  The only other valid value for flags is 0.  This argument may be specified either as a numeric literal or as a @code{PIC X USAGE COMP-X} data item.

Upon completion, the
@registerref{RETURN-CODE} will be set to 0 if the read was successful or to 10 if an "end-of-file" condition occurred.  If a value of -1 is returned, a problem was identified with the subroutine arguments.
@comment *********************************************************************
@comment ** 8.2.45 CBL_READ_KBD_CHAR                                        **
@comment *********************************************************************
@page
@newsubsection{8.2.45,CBL_READ_KBD_CHAR}
@diagram{CBL_READ_KBD_CHAR Build-In Subroutine,SS-CBL_READ_KBD_CHAR,SS-CBL_READ_KBD_CHAR,None}
Waits until a character is typed from the terminal and then read it with no echo.

Parameters: char @code{PIC X}. Receives the character that was typed, in @sc{ASCII}.

status-code @code{PIC XX COMP-5}.

If @code{RETURNING} is not used the @code{RETURN-CODE} special register receives the status-code where zero is success and non-zero it is not.

[Above information taken from MF WB manual].
@comment *********************************************************************
@comment ** 8.2.46 CBL_RENAME_FILE                                          **
@comment *********************************************************************
@page
@newsubsection{8.2.46,CBL_RENAME_FILE}
@diagram{CBL_RENAME_FILE Built-In Subroutine,SS-CBL_RENAME_FILE,SS-CBL_RENAME_FILE,None}
You may use this subroutine to rename a file.

The file specified by @var{old-file-path} will be ``renamed'' to the name specified as @var{new-file-path}.  Each argument may be an alphanumeric literal or data item.

Despite what the name of this routine might make you believe, this routine is more than just a simple ``rename'' --- it will actually move the file supplied as the 1@sup{st} argument to the file specified as the 2nd argument.  Think of it as a two-step sequence, first copying the @var{old-file-path} file to the @var{new-file-path} file and then a second step where the @var{old-file-path} is deleted.

If the attempt to move the file fails (for example, it doesn't exist), the
@registerref{RETURN-CODE} will be set to 128; on successful completion it will be set to 0.
@comment *********************************************************************
@comment ** 8.2.47 CBL_SET_CSR_POS                                          **
@comment *********************************************************************
@page
@newsubsection{8.2.47,CBL_SET_CSR_POS}
@diagram{CBL_SET_CSR_POS Build-In Subroutine,SS-CBL_SET_CSR_POS,SS-CBL_SET_CSR_POS,None}
Set current cursor position on terminal.

This subroutine will set the cursor location on the screen, using a 2-byte value into the supplied @var{cursor-locn-buffer}.  The first byte of @var{cursor-locn-buffer} is for the line (row) location while the second sets the column location.

The two byte data block must be in binary form, and will be based upon starting values of 0, meaning that if the routine is called with a value of (14,11) cursor will be located at line 15, column 12.

The following is a typical @var{cursor-locn-buffer} definition:

@example
01  CURSOR-LOCN-BUFFER.
    05 CURSOR-LINE          USAGE BINARY-CHAR.
    05 CURSOR-COLUMN        USAGE BINARY-CHAR.
@end example
@comment *********************************************************************
@comment ** 8.2.48 CBL_SET_SCR_SIZE                                         **
@comment *********************************************************************
@page
@newsubsection{8.2.48,CBL_SET_SCR_SIZE}
@diagram{CBL_SET_SRC_SIZE Built-In Subroutine,SS-CBL_SET_SCR_SIZE,SS-CBL_SET_SCR_SIZE,None}
Use this subroutine to set the current console screen size.

WARNING: This function may well not be created so this text is really a place holder as no information about its use is currently available - at least as of v3.2 final although it is in one of the compiler source files.

This also means that the definition of this function has NOT been passed to the manual maintainer, i.e., Vincent Coen.
If you know exactly where this is correctly defined, may be in another compiler manual please pass link  of it, or better still the exact definition, thanks.

The following are typical @var{no-of-lines} and @var{no-of-columns} definitions:

@example
01  NO-OF-LINES             USAGE BINARY-CHAR.
01  NO-OF-COLUMNS           USAGE BINARY-CHAR.
@end example

GnuCOBOL run-time screen management must have been initialized prior to CALLing this routine in order to set meaningful values.  This means that a @statementref{DISPLAY data-item} or a @statementref{ACCEPT data-item} must have been executed prior to executing the @statement{CALL}.

Zero values will be returned if the screen has not been initialized and values of 24 (lines) and 80 (columns) will be returned if GnuCOBOL was not generated to include screen I/O.

@comment *********************************************************************
@comment ** 8.2.49 CBL_TOLOWER                                              **
@comment *********************************************************************
@page
@newsubsection{8.2.49,CBL_TOLOWER}
@diagram{CBL_TOLOWER Built-In Subroutine,SS-CBL_TOLOWER,SS-CBL_TOLOWER,None}
This routine will convert the first @var{convert-length} (a numeric literal or data item) characters of @var{data-item} (an alpha-numeric identifier) to lower-case.

The @var{convert-length} argument must be specified @syntaxrefalt{BY VALUE,CALL}.  It specifies how many (leading) characters in data-item will be converted --- any characters after that will remain unchanged.

If @var{convert-length} is negative or zero, no conversion will be performed.
@comment *********************************************************************
@comment ** 8.2.50 CBL_TOUPPER                                              **
@comment *********************************************************************
@page
@newsubsection{8.2.50,CBL_TOUPPER}
@diagram{CBL_TOUPPER Built-In Subroutine,SS-CBL_TOUPPER,SS-CBL_TOUPPER,None}
This routine will convert the first @var{convert-length} (a numeric literal or data item) characters of @var{data-item} (an alpha-numeric identifier) to upper-case.

The @var{convert-length} argument must be specified @syntaxrefalt{BY VALUE,CALL}.  It specifies how many (leading) characters in data-item will be converted --- any characters after that will remain unchanged.

If @var{convert-length} is negative or zero, no conversion will be performed.
@comment *********************************************************************
@comment ** 8.2.51 CBL_WRITE_FILE                                           **
@comment *********************************************************************
@page
@newsubsection{8.2.51,CBL_WRITE_FILE}
@diagram{CBL_WRITE_FILE Built-In Subroutine,SS-CBL_WRITE_FILE,SS-CBL_WRITE_FILE,None}
This routine writes @var{nbytes} of data from @var{buffer} to the byte-stream file defined by @var{handle} starting at byte number @var{offset} within the file.

The @var{handle} argument (@code{PIC X(4) USAGE COMP-X}) must have been populated by a prior call to CBL_OPEN_FILE.
The offset argument (@code{PIC X(4) USAGE COMP-X}) defines the location in the file of the first byte to be written to.  The first byte of a file is byte offset 0.

The @var{nbytes} argument (@code{PIC X(4) USAGE COMP-X}) specifies how many bytes (maximum) will be written.

Currently, the only allowable value for the flags argument is 0.  This argument may be specified either as a numeric literal or as a @code{PIC X(1) USAGE COMP-X} data item.

Upon completion, the
@registerref{RETURN-CODE} will be set to 0 if the write was successful or to 30 if an I/O error condition occurred.  If a value of -1 is returned, a problem was identified with the subroutine arguments.
@comment *********************************************************************
@comment ** 8.2.52 CBL_XOR                                                  **
@comment *********************************************************************
@page
@newsubsection{8.2.52,CBL_XOR}
@diagram{CBL_XOR Built-In Subroutine,SS-CBL_XOR,SS-CBL_XOR,None}
@multitable @columnfractions 0.3 0.7
@item
@verbatim
 Old    Old    New
Arg 1  Arg 2  Arg 2
 Bit    Bit    Bit
=====  =====  =====
  0      0      0
  0      1      1
  1      0      1
  1      1      0
@end verbatim
@tab This subroutine performs a bit-by-bit logical @i{exclusive or} process between the left-most 8*@var{byte-length} corresponding bits of @var{item-1} and @var{item-2}, storing the resulting bit string into @var{item-2}.  The truth table shown to the left documents the @code{XOR} process. @* @* The @var{item-1} argument may be an alphanumeric literal or a data item and @var{item-2} must be a data item.  The length of both @var{item-1} and @var{item-2} must be at least 8*@var{byte-length}.
@end multitable

The @var{byte-length} argument may be a numeric literal or data item, and must be specified using @syntaxrefalt{BY VALUE,CALL}.

Any bits in @var{item-2} after the 8*@var{byte-length} point will be unaffected.

A result of zero will be passed back in the
@registerref{RETURN-CODE}.
@comment *********************************************************************
@comment ** 8.2.53 SYSTEM                                                   **
@comment *********************************************************************
@page
@newsubsection{8.2.53,SYSTEM}
@diagram{SYSTEM Built-In Subroutine,SS-SYSTEM,SS-SYSTEM,None}
This subroutine submits @var{command} (an alphanumeric literal or data item) to a command shell for execution as if it were typed into a console/terminal window.

A shell will be opened subordinate to the GnuCOBOL program issuing the call to @code{SYSTEM}.

Output from the command (if any) will appear in the command window in which the GnuCOBOL program was executed.

On a Unix system, the shell environment will be established using the default shell program.  This is also true when using a GnuCOBOL build created with and for OSX or the Cygwin Unix emulator.

With native Windows Windows/MinGW builds, the shell environment will be the Windows console window command processor (usually @command{cmd.exe}) appropriate for the version of Windows you're using.

To trap output from the executed command and process it within the GnuCOBOL program, use a redirection (@samp{>}) to send the command output to a temporary file which you read from within the program once control returns.

The exit status of the executed command will be available in the @code{RETURN-CODE} special-register.
@comment *********************************************************************
@comment ** 8.2.54 X"91"                                                    **
@comment *********************************************************************
@page
@newsubsection{8.2.54,X"91"}
@diagram{X"91" Built-In Subroutine,SS-X91,SS-X91,None}
The original Micro Focus version of this routine is capable of providing a wide variety of functions.  GnuCOBOL supports just three of them:
@itemize @bullet
@item
Turning runtime switches (@code{SWITCH-1}, @dots{} , @code{SWITCH-8}) on.

@item
Turning runtime switches (@code{SWITCH-1}, @dots{} , @code{SWITCH-8}) off.

@item
Retrieving the number of arguments passed to a subroutine.
@end itemize

The @var{return-code} argument must be a one-byte binary numeric data item (@code{USAGE BINARY-CHAR} is recommended).  It will receive a value of 0 if the operation was successful, 1 otherwise.

The @var{function-code} argument must be either a numeric literal or a one-byte binary numeric data item (@code{USAGE BINARY-CHAR} is recommended).

The third argument --- @var{variable-arg} --- is defined differently depending upon the @var{function-code} value, as follows:
@table @asis

@item 11
Sets and/or clears all eight of the COBOL switches (@code{SWITCH-1} through @code{SWITCH-8}).  @xref{SPECIAL-NAMES}, for an explanation of those switches.

The @var{variable-arg} argument should be an @code{OCCURS 8 TIMES} table of @code{USAGE BINARY-CHAR}.

Each occurrence that is set to a value of zero prior to the @code{CALL X"91"} will cause the corresponding switch to be cleared.  Each occurrence set to 1 prior to the @code{CALL X"91"} will cause the corresponding switch to be set.

Values other than 0 or 1 will be ignored.

@item 12
Reads all eight of the COBOL switches (@code{SWITCH-1} through @code{SWITCH-8})

The @var{variable-arg} argument should be an @code{OCCURS 8 TIMES} table of @code{USAGE BINARY-CHAR}.

Each of the 1@sup{st} eight occurrences of the array will be set to either 0 or 1 --- 1 if the corresponding switch is set, 0 otherwise.

@item 16
Retrieves the number of arguments passed to the program executing the @code{CALL X"91"}, saving that number into the @var{variable-arg} argument.  That should be a binary numeric data item (@code{USAGE BINARY-CHAR} is recommended).
@end table
@comment *********************************************************************
@comment ** 8.2.55 X"E4"                                                    **
@comment *********************************************************************
@page
@newsubsection{8.2.55,X"E4"}
@diagram{X"E4" Built-In Subroutine,SS-XE4,SS-XE4,None}
Use @code{X"E4"} to clear the screen.  There are no arguments and no returned value.
@comment *********************************************************************
@comment ** 8.2.56 X"E5"                                                    **
@comment *********************************************************************
@newsubsection{8.2.56,X"E5"}
@diagram{X"E5" Built-In Subroutine,SS-XE5,SS-XE5,None}
The @code{X"E5"} routine will sound the PC ``bell''.  There are no arguments and no returned value.
@comment *********************************************************************
@comment ** 8.2.57 X"F4"                                                    **
@comment *********************************************************************
@page
@newsubsection{8.2.57,X"F4"}
@diagram{X"F4" Built-In Subroutine,SS-XF4,SS-XF4,None}
This routine packs the low-order (rightmost) bit from each of the eight 1-byte items in @var{table} into the corresponding bit positions of the single-byte data item @var{byte}.

The @var{byte} data item need be only a single byte in size.  If it is longer, the excess will be unaffected by this subroutine.

The @var{table} data item must be at least 8 bytes long.  If it is longer, the excess will be ignored by this subroutine.

Typically, table is defined similarly to the following:

@example
01  Table-Arg.
    05 Each-Byte OCCURS 8 TIMES USAGE BINARY-CHAR.
@end example
@comment *********************************************************************
@comment ** 8.2.58 X"F5"                                                    **
@comment *********************************************************************
@page
@newsubsection{8.2.58,X"F5"}
@diagram{X"F5" Built-In Subroutine,SS-XF5,SS-XF5,None}
This routine unpacks each bit of the single-byte data item @var{byte} into the low-order (rightmost) bit of each of the corresponding eight 1-byte items in @var{table}.  The other seven bit positions of each of the first eight entries in @var{table} will be set to zero.

The @var{byte} data item need be only a single byte in size.  If it is longer, the excess will be unaffected by this subroutine.

The @var{table} data item must be at least 8 bytes long.  If it is longer, the excess will be ignored by this subroutine.

Typically, table is defined similarly to the following:

@example
01  Table-Arg.
    05 Each-Byte OCCURS 8 TIMES USAGE BINARY-CHAR.
@end example
@iftex
@sp 3
@center ------------------------------------------------------------
@center End of Chapter 8 --- Functions
@end iftex