COBOL-callable Program Library

P3/COBOL includes a library of useful programs that can be directly called by user applications. These programs are written in Java and provide easy access to utility functions within the P3/COBOL runtime environment.

RM/COBOL Compatible Subroutines

Many of the RM/COBOL¹ C$ library subprograms are provided in P3/COBOL. These subroutines mimic the functionality of corresponding RM/COBOL¹ library routines and are as follows:

• c$carg
• c$darg
• c$delay
• c$forget
• c$logicaland
• c$logicalor
• c$logicalxor
• c$memoryallocate
• c$memorydeallocate
• c$narg
• c$getenv
• c$getlastfilename
• c$getlastfileop
• c$getrminfo
• c$getsysinfo
• c$logicalshiftleft
• c$logicalshiftright
• c$rerr
• c$securehash
• c$setdevelopmentmode
• c$setenv
• c$show
• c$sleep
• c$system (SYSTEM)
• c$title
• c$wru
• xmlimportfile
• xmlexportfile

MVCC Indexed File Volume Utilities

These subroutines allow housekeeping functions to be performed on indexed organization files stored within MVCC volume files.

p3$backup

USING volume-path, backup-file-path [RETURNING status-return]

Where:

01 volume-path                  pic x(...).
01 backup-file-path             pic x(...).
01 status-return                pic s9(5).
    88 is-ok                    value  0.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-backup-error          value -3.

This subroutine causes the designated volume to be backed up to the indicated backup file. The backup file will be in the form of a snapshot of the volume file at the time of the backup. It may be restored by simply using the resulting volume as it is. The state of the restored volume will be that of the volume when it was backed up, with only complete COBOL file operations reflected. Transactions that were incomplete (i.e., in progress or rolling back) at the time of the backup operation will not be applied. This could cause some operations concurrent with the backup (if any) to not be reflected in the backup volume. If the volume is inactive at the time of the backup (i.e., no files open), there would be no loss of information.

p3$backup-zipped

USING volume-path, backup-file-path [RETURNING status-return]

Where:

01  volume-path                 pic x(...).
01  backup-file-path            pic x(...).
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-backup-error          value -3.

This subroutine causes the designated volume to be backed up to the indicated backup file. The backup file will be in the form of a compressed (zip) version of the volume file at the time of the backup. It may be restored by unzipping the file and using the resulting volume as it is. The state of the restored volume will be that of the volume when it was backed up, with only complete COBOL file operations reflected. Transactions that were incomplete (i.e., in progress or rolling back) at the time of the backup operation will not be applied. This could cause some operations concurrent with the backup (if any) to not be reflected in the backup volume. If the volume is inactive at the time of the backup (i.e., no files open), there would be no loss of information.

p3$compact

USING volume-path [RETURNING status-return]

Where:

01  volume-path                 pic x(...).
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-compact-error         value -3.

This subroutine causes the designated volume to be compacted. If the volume is inactive, the compaction will occur immediately. If there are one or more files open on the volume, the compaction will normally be done when the last file open on the volume is closed (i.e., the volume becomes inactive). This effect is the same as if the compact volume-configuration option had been used.

p3$delete

USING volume-path, file-name [RETURNING status-return]

Where:

01  volume-path                 pic x(...).
01  file-name                   pic x(...).
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-no-file               value  1.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-delete-error          value -3.

This subroutine causes the designated file on the specified volume to be removed (i.e., the file-name will no longer refer to the file). The file data, however, is retained on the volume until a compact operation is successfully performed. Until that time, the data may be recovered. The file-name may be re-used for new file data upon successful completion of this subroutine.

p3$rename

USING volume-path, name-pattern, new-name [RETURNING status-return]

Where:

01  volume-path                 pic x(...).
01  name-pattern                pic x(...).
01  new-name                    pic x(...).
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-rename-error          value -3.

This subroutine renames the files whose names match the name-pattern regular expression residing on the indicated volume. The new-name provided serves as a substitution name in a manner similar the external-name in the file-association configuration element. This allows groups of files to be renamed, and the use of capture groups from the name-pattern in the new-name.

p3$diff

USING volume-path-from, volume-path-to, log-file-name [RETURNING status-return]

Where:

01  volume-path-from            pic x(...).
01  volume-path-to              pic x(...).
01  log-file-name               pic x(...).
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-no-file               value  1.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-diff-error            value -3.

This subroutine causes the file and record-level differences (the "delta") between the two volumes specified to be determined and recorded in the specified log file. The differences are reflected by records in the log file that, if re-played programmatically, will if given the "from" volume produce the "to" volume content. Each record in the log has the following structure:

01  log-record.
    10 log-type                 pic x.
       88 is-file-log           values "=", ">", "<", "*".
       88 is-record-log         values "/", "+", "-".
       88 is-file-changed       value "=".
       88 is-file-deleted       value ">".
       88 is-file-added         value "<".
       88 is-record-changed     value "/".
       88 is-record-added       value "+".
       88 is-record-deleted     value "-".
       88 is-file-detail        value "*".
    10 log-payload.
       20 filler                pic x(1000).
    10 log-payload-n            pic n(500) redefines log-payload.

The log-type determines the meaning of each individual record. If is-file-log, the record pertains to the addition, deletion, or change of a file relative to the state of the "from" volume. In this case, the balance of the record (the log-payload) is the name of the file, in national characters (Unicode-16), and can be accessed using the log-payload-n redefinition. If is-record-log is true, then the record pertains to the addition, deletion, or change of a record in the last indicated file (the last is-file-changed record). The balance of the record (the log-payload) contains the full record image of the added, deleted, or changed record.

p3$diff-zipped

USING volume-path-from, volume-path-to, log-file-name [RETURNING status-return]

This subroutine operates exactly as the p3$diff subroutine, except that the log file produced is zipped.

p3$check-diff

USING volume-path-from, log-file-name[, zipped-indicator] [RETURNING status-return]

or

USING log-file-name [RETURNING status-return]

Where:

01  volume-path-from            pic x(...).
01  volume-path-to              pic x(...).
01  log-file-name               pic x(...).
01  zipped-indicator            pic 9.
    88 is-zipped                value not = 0.
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-no-file               value  1.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-diff-error            value -3.

This program causes the file and record-level differences (the "delta") in the specified log file to be checked as applied to the indicated volume or, if no volume is specified, the current file environment. If the status returned indicates success, the log file was read successfully and every file referenced by the log was consistent with the volume indicated or the current environment. In other words a subsequent p3$apply-diff could be expected to be successful given the current state of the supplied parameters.

p3$apply-diff

USING volume-path-from, log-file-name[, zipped-indicator] [RETURNING status-return]

or

USING log-file-name [RETURNING status-return]

Where:

01  volume-path-from            pic x(...).
01  volume-path-to              pic x(...).
01  log-file-name               pic x(...).
01  zipped-indicator            pic 9.
    88 is-zipped                value not = 0.
01  status-return               pic s9(5).
    88 is-ok                    value  0.
    88 is-no-file               value  1.
    88 is-arg-error             value -1.
    88 is-wrong-no-args         value -2.
    88 is-diff-error            value -3.

This program causes the file and record-level differences (the "delta") in the specified log file to be applied to the indicated volume or, if no volume is specified, the current file environment. If the status returned indicates success, the volume or current environment is now consistent with the volume or environment at the time the difference log was produced.

Histogram Subroutines

p3$histogram

USING control [RETURNING status-return]

Where:

⏱️ This program allows control over the stopping, starting, and dumping of the configured histogram.