DOWNLOAD PC FILE

#### Search Results

Search

# DOWNLOAD PC FILE

| `DOWNLOAD` `WRITE` |  |  | `PC` `WORK` |  | [`FILE`] work-file-number |  | [`VARIABLE`] operand1 [(parameter)] |
`COMMAND` operand2 |  | `SYNC` `ASYNC` |

This document covers the following topics:

- DOWNLOAD PC FILE Usage

- DOWNLOAD PC FILE Syntax Description

- External Representation of Fields

- DOWNLOAD PC FILE Examples

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: `CLOSE PC FILE` | `UPLOAD PC FILE` | `WRITE WORK FILE`

Belongs to Function Group: Control of Work Files / PC Files

## DOWNLOAD PC FILE Usage

This statement is used to transfer data to the PC.

See also the Natural Connection and Entire Connection documentation

## DOWNLOAD PC FILE Syntax Description

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S | A | G |  | A | U | N | P | I | F | B | D | T | L | C | yes | no
`operand2` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  | yes | yes

Neither Format C not G is valid for Natural Connection.

Syntax Element Description:

Syntax Element | Description
--- | ---
`work-file-number` | Work File Number: The work file number to be used. This number must correspond to one of the work file numbers for the PC as defined to Natural.
`VARIABLE` | Variable Format: The records in the PC file will be written in variable format. Note that variable records cannot be converted to PC spreadsheet formats.
`operand1` | Field Specification: With `operand1` you specify the fields to be downloaded to the PC.
`COMMAND` | COMMAND Clause: With the `COMMAND` clause, you can send PC commands (that is, any command that can be entered in the command line of Entire Connection on the PC) to the PC. Entire Connection checks whether the command sent is valid or not. A command that cannot be recognized by the PC is rejected. In this case, Natural issues the error message that the downloaded command was rejected by the PC. You can use the `COMMAND` clause, for example, to execute Entire Connection tasks from z/OS. If you have the task `DIR` which lists PC directory information, you can initiate this directly out of your Natural program on z/OS with the following statement:
    DOWNLOAD PC FILE 7 COMMAND 'DIR'
In Example 2 below, the `COMMAND` clause is used to define the name of the PC file that is to receive the downloaded data. In this way, you can avoid prompting for the name of the file.
`operand2` | COMMAND Specification: With `operand2`, you specify the DOS command or Entire Connection task that is to be executed on the PC. `operand2` must be an alphanumeric constant or variable.
`SYNC` | SYNC Option: With `SYNC`, you specify that the PC returns control to Natural after executing and terminating `COMMAND`. `SYNC` can be used, for example, to ensure that the command `SET PCFILE` has been executed before a file transfer starts.
`ASYNC` | ASYNC Option: With `ASYNC`, you specify that the PC immediately returns control to Natural, regardless of whether the execution of `COMMAND` has terminated or not.
`parameter` | Edit Mask Parameters: With `parameter`, you can specify the session parameter `EM` or `EMU`:
`EM=` | Edit Mask: For details on edit masks, see the session parameter `EM` in the Parameter Reference. The `EM` parameter cannot be applied to group operands.
`EMU=` | Unicode Edit Mask: For details on Unicode edit masks, see the session parameter `EMU` in the Parameter Reference. The `EMU` parameter cannot be applied to group operands.

## External Representation of Fields

Fields written with a `DOWNLOAD PC FILE` statement are represented in the external file according to their internal definition unless an edit mask is applied.

- Fields without Edit Masks
  No editing is performed on the field values. The field values are written in their internal format.

- Fields with Edit Masks
  The field is first formatted as per the specified edit mask. The resulting formatted value is written to the work file.

### Fields without Edit Masks

For fields written without edit masks:

- Format A and B:
  The number of bytes in the external file is the same as the internal length defined in the Natural program. No editing is performed, and a decimal point is not included in the value.

- Format N:
  The number of bytes in the external file equals the sum of the internal positions before and after the decimal point. The decimal point is not included in the output.

- Format P:
  The number of bytes in the external file equals the sum of positions before and after the decimal point, plus 1 for the sign, divided by 2, and rounded up to the next full byte.

Note
No format conversion is performed for fields written without edit masks.

Examples of field representations (without edit masks):

Field Definition | Output Record
--- | ---
`#FIELD1 (A10)` | 10 bytes
`#FIELD2 (B15)` | 15 bytes
`#FIELD3 (N1.3)` | 4 bytes
`#FIELD4 (N0.7)` | 7 bytes
`#FIELD5 (P1.2)` | 2 bytes
`#FIELD6 (P6.0)` | 4 bytes

### Fields with Edit Masks

When an edit mask is applied to a field, the field value is converted using the specified edit mask and resulting formatted value is written to the work file.

- The internal representation is not used in this case.

- The length of the value written to the file corresponds to the length of the resulting formatted string.

## DOWNLOAD PC FILE Examples

- Example 1 - Use of DOWNLOAD PC FILE Statement

- Example 2 - Use of COMMAND Clause

- Example 3 - Use of DOWNLOAD PC FILE Statement with Edit Mask

### Example 1 - Use of DOWNLOAD PC FILE Statement

The following program demonstrates the use of the `DOWNLOAD PC FILE` statement. The data is first selected and then downloaded to the PC by using Work File 7.

    ** Example 'PCDOEX1': DOWNLOAD PC FILE
    **
    ** NOTE: Example requires that Natural Connection is installed.
    ************************************************************************
    DEFINE DATA LOCAL
    01 PERS VIEW OF EMPLOYEES
      02 PERSONNEL-ID
      02 NAME
      02 CITY
    END-DEFINE
    *
    FIND PERS WITH CITY = 'NEW YORK'                     /* Data selection
      DOWNLOAD PC FILE 7 CITY NAME PERSONNEL-ID    /* Data download
    END-FIND
    END

#### Output of Program PCDOEX1:

When you run the program, a window appears in which you specify the name of the PC file into which the data is to be downloaded. The data is then downloaded to the PC.

### Example 2 - Use of COMMAND Clause

The following program demonstrates the use of the `COMMAND` clause in the `DOWNLOAD PC FILE` statement. The name of the receiving PC file is first defined. Then the data is selected and downloaded to this file.

    ** Example 'PCDOEX2': DOWNLOAD PC FILE
    **
    ** NOTE: Example requires that Natural Connection is installed.
    ************************************************************************
    DEFINE DATA LOCAL
    01 PERS VIEW OF EMPLOYEES
      02 PERSONNEL-ID
      02 NAME
      02 CITY
    01 CMD (A80)                                   /* Variable for transfer
    END-DEFINE                                     /* of the PC command
    *
    MOVE 'SET PCFILE 7 DOWN DATA PERS.NCD' TO CMD  /* PC command to define
    *
    DOWNLOAD PC FILE 6 COMMAND CMD                 /* Command download
    *
    FIND PERS WITH CITY = 'NEW YORK'               /* Data selection
      DOWNLOAD PC FILE 7 CITY NAME PERSONNEL-ID    /* Data download
    END-FIND
    END

Note
The PC file number in two successive `DOWNLOAD PC FILE` statements must be different.

#### Output of Program PCDOEX2:

When you run the program, the data is downloaded to the PC file that was specified in the program. A window does not appear.

### Example 3 - Use of DOWNLOAD PC FILE Statement with Edit Mask

The following program demonstrates the use of the `DOWNLOAD PC FILE` statement. The data is first selected and then downloaded to the PC by using Work File 6.

    ** Example 'PCDOEX3': DOWNLOAD PC FILE with Edit Mask
    **
    ** NOTE: Example requires that Natural Connection is installed.
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 PERSONNEL-ID
      2 NAME
      2 CITY
      2 BIRTH
    END-DEFINE
    *
    FIND EMPLOY-VIEW WITH CITY = 'MADRID'
      DOWNLOAD PC FILE 6
            PERSONNEL-ID NAME BIRTH (EM=YYYY/MM/DD)
    END-FIND

#### Output of Program PCDOEX3:

When you run the program, the data is downloaded to the PC file that was specified in the program. A window does not appear.

### On this page

- DOWNLOAD PC FILE Usage
- DOWNLOAD PC FILE Syntax Description
- External Representation of Fields
- DOWNLOAD PC FILE Examples