|
|
|
DOCPICK, an assembly language program, is the first step in
the process of printing one of the CA MICS guides. It
combines text members which contain the document sections,
figures, and title pages to produce a rough version of the
final text. This combination is done under the control of a
picklist which names, in sequence, the members that make up
the text. The output from DOCPICK is input to the formatting
program DOCUMENT. This program produces the final version of
the text. DOCUMENT is discussed in Section 4.6.3.
The files used by DOCPICK are:
- DOCSTRM
This input file contains the picklist members.
- DOCUMENT
This input file contains the document text members
selected with the $SMEM and $LMEM commands.
- DATADICT
This input file contains data dictionary members selected
with the $DMEM command.
- DOCOUT
This is the principal output file. It contains the
members selected from DOCUMENT and DATADICT under the
control of the picklists in DOCSTRM.
- SYSTERM
This output file is used for error messages. It is
optional, and if it is not present, messages are
discarded.
- DOCIN
This is an optional sequential input file. If present, it
is treated as the first level of input, equivalent to the
DOCSTRM file. This file is used mainly in batch as an
instream file for ad hoc print requests. This file is, in
effect, a sequential picklist, one level above the DOCSTRM
file. If present, it overrides the M= exec parm that
normally specifies the starting level picklist.
DOCPICK RETURN CODES
0 - Everything OK
1 - at least one member was not found
2 - no output records or table rows produced
4 - Error opening files
8 - EXEC parm error, see systerm message
12 - VCOPY string field too long
16 - File blksize problem
20 - SYNAD routine entered, I/O problem
24 - Bad problem, program issued quit without diagnosis
28 - VDELETE failed
32 - WILD Card Specification Error
36 - Unsuccessful load of ISPLINK
40 - VCOPY or VDEFINE error
DOCPICK PROCESSING
The operation of DOCPICK can be described as follows:
DOCPICK reads the picklist looking for four types of control
cards. They are:
- $COPY (copy a picklist member)
- $SMEM (short text member)
- $LMEM (long text member)
- $DMEM (DIC.TEXT member)
DOCPICK processes each card as follows:
- $SMEM
The member is copied from the DOCUMENT file. The control
card is discarded.
- $LMEM
$SPAG and $LONG control records are written to DOCOUT, the
member is copied from the DOCUMENT file, and then a $REST
control record is written to DOCOUT. Carriage control
characters are removed and spacing lines added instead.
The control card is discarded.
- $DMEM
The same action is taken as for $SMEM cards, except the
control card is first copied to the DOCOUT file, as well.
- $COPY
Names a picklist member that is inserted in the text where
the $COPY card appears. When it appears in a picklist,
the copied member is treated as an insertion to the
picklist rather than to the text being built.
$COPY, $SMEM, $LMEM, and $DMEM statements can be nested up
to 10 levels deep.
All other $xxxx control cards are simply copied to the DOCOUT
file.
DOCPICK is normally executed in conjunction with DOCUMENT.
The JCL needed to execute both of these programs is the
MICSDOC Proc.
How DOCPICK handles short and long members:
- From a picklist (assumed a $SMEM itself)
To an $SMEM or $DMEM - no special processing
To an $LMEM - issue a $SPAG, then a $LONG before
copying
- issue a $REST after copying
- During transition within a text member (nested copy)
From an $SMEM or $DMEM to an $LMEM
- issue a $SPAG, then a $LONG before copying
From an $LMEM to an $SMEM or $DMEM
- issue a $REST after copying
The logic above applies to the $COPY command as well, based
on the rules outlined for how $COPY short/long type is
determined.
Special note on LMEMs:
As a convenience, DOCPICK assumes that carriage control
characters in column 1 of a long member should be
converted to extra line or page skips before passing the
text on to the DOCUMENT program. This makes it easier to
plug reports output directly into the documentation. This
feature is still supported for the standard processing
option, but is suppressed for unload type options, such as
CNTL and CTLC.
Book Picklist
-------------
$COPY PIC... >>> Chapter Picklist
----------------
$xMEM membername >>> Text Member
----------------
$xMEM membername >>> Copy Member
$COPY ------------
$xMEM membername ...
$COPY
Figure 4-2. DOCPICK Nested Copy Processing
In the figure above, $xMEM refers to SMEM, LMEM, or DMEM.
These commands will now allow $COPY-type operations on any
member, regardless of its name. LMEMs are treated as 133
characters wide. SMEMs and DMEMs are treated as 80 columns
wide, but normally using only 62 columns. For variable
length records, the full length of the record is processed,
but certain options and formats require short/long text
conventions to followed (e.g., 2UP, SN, $CENT, etc.).
$COPY will try to determine the type of member based on #INS
and #INL naming conventions. If the fourth character of the
name is "S", assume a short member, if the fourth character
is "L", assume a long member; otherwise, assume that copy
member is the same type as the calling member, meaning don't
do anything special about changing page format, just copy the
text.
DOCPICK stacks the member type along with the other
information stored when a COPY or xMEM command is processed.
The types are S, L, or D, which describes the format and also
the DD type to use for the copy operation. One parameterized
read routine is used. DDnames for each type S,L, or D are
determined at program initialization based on what DDs have
been provided, as follows:
$SMEM - DOCUMENT - required
$DMEM - DATADICT - optional (use DOCUMENT DD if not present)
Thus, all xMEM commands can run off the single DDname of
DOCUMENT, or off separate DDnames, if needed.
Using VB text format, separate DDnames are not needed to
support 80 vs. 133 character record lengths. The DATADICT
DD allows for a self-contained member naming scheme for
dictionary elements that will not come in conflict with text
section naming conventions. Example: ID is a data element
but would also be Chapter 13 of the Database Structure and
Content Guide (if that book had a Chapter 13).
DOCPICK OPTIONS - (passed through an EXEC parm)
- CMD
Output $commands only - no text. An unload option for
analysis of $command structure, copy cross references,
compare picklist title to hedr title, etc.
- CNTL
Unload text in DOCUPDT format (./ control records).
Embedded copy commands are not resolved in text.
- CTLC
Same as CNTL, except all copy commands are resolved.
Embedded copy commands themselves are left in the text.
This option is for input to the text cross reference
program. Since this program needs to know the type of
member (S,L,D), and the guide ID to which it belongs,
these two additional pieces of information are output on
the ./ control records in columns 32 and 34 respectively.
I=id should also be specified.
- FMT
Format the output for the browse/print user rather than
for guide production. Convert $SPAG, $HEDx, $SCOL, $REST
to carriage control. Add spaces for browse. Convert
$HEDx to a title, etc.
- I=id
Supplies the Doc Identifier for T= processing. Allows
DOCPICK to determine docID length and string value. Also
used for CTLC guide ID output.
- K=section key prefix
Used mainly by Document Browse; requests that only those
members that logically belong to the specified section key
be picked, and that all other members be ignored. For
example, K=0103 would specify that only sections and
figures belonging to 1.3 be picked. This means that FD13
and FD13n would be picked, but FD1 and FD2 would not.
Note that the key of a figure is the same as the section
number preceding it.
- L=level limit
Used mainly by Document Browse, requests that only those
members that logically belong to "level limit" or less be
picked, and that all members that belong at a level
greater than the limit be ignored. For example, L=2 would
specify that only level 1 or level 2 sections and figures
be picked. This means that FD1 and FD11 would be picked,
but FD111 would not. Note that the level of a figure is 1
greater than the section number preceding it.
- M=member
Member name of picklist starting point or individual text
member to print. Alternative to supplying member name in
the DOCSTRM JCL statement. Allows for concatenation on
the DOCSTRM DD.
- N=output file number
Character string suffix appended to the name DOCOUT to
allow the program to write to the DOCOUTn DDNAME. This
option is used by Document Browse to allow for different
output files for each side of split screen. The value of
the Dialog Manager variable ZSCREEN is used as the file
name suffix. It is set on the call to DOCPICK as
N=&ZSCREEN.
- S=pref
Apply pref string as prefix selection on member names to
be picked. Only members with names beginning with pref
are written to output.
- SN
Strip line numbers on input. Will blank out cols 73-80 on
all lines assumed to be from SMEMs.
- T=tname
Requests that Table of Contents ISPF Table "tname" be
built from picklists. No text is picked; the program
simply runs through the picklist structure.
- UCASE
Requests that DOCPICK translate text to upper case. This
option is for sites which do not have upper/lower case
print capability. The option is activated by specifying
"UCASE" in the PARM parameter of the EXEC card (or via the
CASE parameter if MICSDOC is being used). When using the
option from the PROC, the parameter is also passed to the
DOCUMENT program.
- VCOPY
Requests that Dialog Manager services variable DOCPVM
should be VCOPYed for list of members to pick, rather than
using a picklist. Used by the Browse (B) line command.
DOCPVM contains a list of one or more type-name strings of
the form tnnnnnnnn tnnnnnnnn ... etc. T is the Xmem type
(S,L,D) or C for $COPY of a picklist. nnnnnnnn is the
member name. This string is treated like a compact form
of a picklist.
The $WILD command is also supported through this variable
in the following format: Wpppppppp*vvvvvvvv, where "p"
represents a 1 to 8 character pattern name and "v"
represents a 1 to 8 character wildcard replacement value.
DOCUMENT ACCESS
Document Access uses the DOCPICK program to:
- Build the ISPF tables used for table of contents
browse.
- Pick line selected members chosen by the user and
format them into a browse/print temporary data set.
- Pick a subset of members named in a picklist by
selecting on member name substrings (leading string
only).
- Unload entire guides in a form usable by the Subject
Cross reference file build process.
THE DOCIN FILE
DOCIN is a SYSIN type sequential input file in DOCPICK, which
can be used to pass information about component selection to
the DOCPICK program executing in batch. This file is
optional, and if present, reads the selection information
generated by Document Access during the construction of the
print job. Use of this input file removes the constraint
that all information must reside in a PDS in one of the
concatenations of input files used by DOCPICK.
A similar capability is provided for interactive execution of
DOCPICK under ISPF. This is done by passing the component
selection information through the DOCPVM dialog manager
variable currently used by Document Browse for member
selection.
| Copyright © 2012 CA. All rights reserved. | Tell Technical Publications how we can improve this information |