HP 3000 Manuals

HP Data Entry and Forms Management System (VPLUS/V)

VOPENBATCH 

Opens existing batch file for processing; or, if the specified file is
new, creates a batch file and then opens it for processing.

Syntax 

             VOPENBATCH {comarea,batchfile}

Parameters 

comarea          Must be comarea name specified when the forms file was
                 opened with VOPENFORMF. If not already set, the
                 following comarea items must be set before calling
                 VOPENBATCH:

                 cstatus          Set to zero.

                 language         Set to the code identifying the
                                  programming language of the calling
                                  program.

                 comarealen       Set to total number of two-byte words
                                  in comarea.

                 VOPENBATCH sets the following comarea items:

                 nfname           Set to the name of the form
                                  corresponding to the record identified
                                  by recnum.

                 recnum           Set to zero if new file opened; to the
                                  next sequential record number if
                                  existing file opened.

                 numrecs          Set to zero if new file opened; to the
                                  number of nondeleted records in file if
                                  existing file opened.

                 VOPENBATCH may set the following comarea items:

                 cstatus          Set to nonzero value if call
                                  unsuccessful.

                 filerrnum        Set to file error code if MPE file
                                  error.

batchfile        Character string of up to 36 characters (including a
                 terminator) that identifies the batch file being opened.
                 Specified name can be any fully qualified MPE file name.

Discussion 

VOPENBATCH opens the specified batch file for processing by the calling
program.  The batch file may be an existing file or a new file.

Existing File 

If the named file already exists, VOPENBATCH initializes recnum to the
record number of the next record in the file, and numrecs to the total
number of existing batch records.  Thus, a user resuming collection does
not overwrite data collected into previous batch records.  VOPENBATCH
sets nfname to the name of the form associated with the batch record to
be collected.  This record is identified by recnum.  VOPENBATCH keeps
track of forms sequence in order to associate a form with a record.  For
example, if a batch file is closed after record 6 of FORMA was collected,
and FORMA is a repeating form, the batch file starts with record 7 FORMA
when it is next opened by VOPENBATCH.

VOPENBATCH also resets the global environment (save fields and so forth)
to the environment existing when collection stopped.  (All this
information is derived from the file labels preceding each file.)

New File 

If the named file does not exist, VOPENBATCH creates a new file with the
specified name and sets recnum and numrecs to zero.  A new batch file
created by VOPENBATCH has the following characteristics:

* Non-KSAM file           * Update access

* USASCII coded data      * Exclusive (nonshared) access

* Fixed-length records    * No dynamic locking

* No carriage control     * No multirecord access

* :FILE command allowed   * Normal buffering
(use actual file
designator)
Record Format 

The size of the fixed-length batch file records must be large enough to
hold the largest data buffer used by the forms file associated with the
batch file, plus 10 two-byte words for batch record control information.
If the largest data buffer is an even number of bytes, an additional
two-byte word is added before the control information.  This batch record
information consists of:

2 bytes          --Delete flag (TRUE if record deleted)
(logical)

16 bytes         --Current form name + extra character
(character)

2 bytes          --Data buffer length
(logical)

Total = 20 bytes

The above batch record information is written at the end of each record
in the batch file, starting on a two-byte word boundary.  To illustrate,
assume the record size is 74 bytes, and the data only requires 35 bytes
(bytes are numbered from 1):


Labels 

In addition, VOPENBATCH creates sufficient user labels (each 256 bytes
long) to hold any save field buffers, plus 176 bytes for the collection
environment and the forms file version.

The length of the save field buffers depends on how many (if any) save
fields were defined for the form and the length of each.  The collection
environment consists of the forms file name and version number, the next
form name, and 122 bytes of system information.  This information is
stored as follows:

   # of Bytes                                        
---------------------------------------------------------------------------------------

        2         --Product number
        2         --(System use)
        4         --Forms file version (date and time of compilation)
       16         --Next form name
       28         --Forms file name
       120        --Reserved for system use
        4         --Number of nondeleted records in batch file

          Total = 176

For example, assume that the save fields buffer requires 242 bytes.  The
following user labels are created by VOPENBATCH:

LABEL 0--Contains first 80 bytes of Save Fields buffer


LABEL 1--Contains remaining 162 bytes of Save Fields buffer


Note that the length of the save fields buffers is determined by taking
the number of bytes in each save field, summing them together, adding one
byte, and then, if odd, rounding the total up to an even number.

Creating Your Own Batch File 

Should you want to create your own batch file rather than calling
VOPENBATCH, you must build the file using the above record format and
user label requirements.  Also, if you create a batch file with
variable-length or undefined-length records rather than fixed-length
records, browsing of the batch file is not allowed.  Undefined-length
records are formatted like fixed-length records.

If you do, nevertheless, want to create a batch file with variable-length
records for data collection only, the batch file information is stored
immediately following the data in each record.  Assume a variable-length
record with 35 bytes of data:


The total size of this record is 56 bytes.  Depending on the size of the
data, other records have varying lengths.  The maximum size of the
variable-length records must be the size of the largest data buffer (in
bytes) plus 20 bytes for the batch record information.

Example 

COBOL

            CALL "VOPENBATCH" USING COMAREA, BATCH.

BASIC

            170 CALL VOPENBATCH(C(*),Bl$)

FORTRAN

            CALL VOPENBATCH(COMAREA,BATCH)

SPL/PASCAL

            VOPENBATCH(COMAREA,BATCH);

If the requested batch file name is an existing file, it is opened and
the user can continue to enter data into the record following the last
record that contains data.  If the requested batch file name is a new
file, VOPENBATCH creates a batch file and data entered at the terminal is
written to the first record in the file (record 0).

MPE/iX 5.0 Documentation