CP

See also:
POS RETCMS in this section.
Issuing CP commands in section VM/CMS Processing.

   _____________________________________________________________
  |        |                         |                          |
  |        |            n AT p1      |                          |
  |        |                         |                          |
  |        |               L         |              n AT p3     |
  |        |          p1  LEN   n    |                          |
  |        |             LENGTH      |                  L       |
  |        |  FROM =      LRECL      |   REPLY     p3  LEN   n  |
  |   CP   |                         |          =     LENGTH    |
  |        |            p1 (,p2)     |   INTO          LRECL    |
  |        |                         |                          |
  |        |             'lit'       |                          |
  |        |_________________________|             p3  (,p4)    |
  |        |                         |                          |
  |        |      'lit'              |                          |
  |________|_________________________|__________________________|

Arguments p1, p2 and n are supported also as @ and @user pointer values or Position Keywords.

For use in CMS mode only, with DOS set ON or OFF, the CP parameter may be used to issue CP commands from within a SELCOPY execution.

Literals must be in enclosed in quotes otherwise incorrect spelling of a legal parameter could be processed as a literal.
Beware that CP must have its commands provided in upper case and SELCOPY's literals in quotes always retain their upper/lower case integrity.

REPLY Parameter

Length of the REPLY area may be defined at any value using the above syntax. (The 8192 byte restriction no longer exists on current versions of CP.)

If no REPLY length is provided, then the remainder of the work area is made available, starting from the position p3.

Because the CP reply is of variable length, SELCOPY will place four asterisks immediately following the reply. This will occur even for CP commands with no reply, as in the example below for instance. In that example, no REPLY/INTO parameter was supplied for the CP reply, so the default of INTO=1 is assumed. The CP reply is of zero length, so position 1 to 4 will be overwritten with '****' by SELCOPY.

If a CP statement supplies a length for the REPLY data and the reply from CP is not at least 4 bytes less than this length, then "****" is no longer appended by SELCOPY to the CP reply data, even when sufficient space exists beyond the reply area within the confines of the WORKLEN parameter.

CP's reply uses X'15' as a line separator, which for console devices is the New Line character. In fact, CP will accept multiple commands from the caller if they are separated by X'15' characters.
e.g.

CP 'Q DASD'  REPLY 900 AT 101 * Restrict reply to 900 bytes.
CP 'Q DASD'                   * Reply may use whole of workarea.
THEN CP 'QUERY RDR ALL'   INTO 101    STOPAFT 1
ELSE CP   FROM=1 LEN=20    REPLY @BEG,@END   STOP=1

Return Code

It is possible however for CP to return a zero return code (indicating success) but a bad condition code (indicating failure). e.g. when the REPLY area is too small.
In such cases, SELCOPY will overrule the CP Return Code by setting it to 256, thereby allowing the user to recognise success with a single test. Also the first character of the reply area is overwritten with a "not" sign (X'5F').

Use IF 4 AT RETCMS TY=B = 0 in preference to testing for asterisks or not signs. It is inconvenient to have storage overwritten when it may contain data that is still required.

A later release of SELCOPY may remove the current action of overwriting the work area with Return Code information.

Reply to Terminal

CMS 'CP QUERY NAMES'

Example

&BEGSTACK
  READ    '* LISTING W'   DIRDATA   INTO=44   W=200
  IF POS 44,44+LRECL-1 = 'ERROR'
           * ....,....1....,....2....,....3....,....4...
    T P 1 = 'MSG OPERATOR --ERROR FOUND IN xxxxxxxx--'
    T MOVE 8   FR DSN   TO 31      * Fname of current file.
    T CP  FR 1   L=70              * Send message to Operator,
                                   *   using data from a CMS file.
    T LOG FR 1   L=70              * Same message on user's TERM.
    T FLAG EOMEMB                  * Only 1st for each file.
&END
EXEC SELC

Prohibited Use

ERROR 115   PRIVILEGED COMMAND (CP/CMS/STACK)