DAP interface routines

3.2 DAP interface routines

3.2.1 dapcon and daprel

arguments to dapcon

You transfer control and data between host and DAP programs using AMT-supplied interface routines dapoon, dapent, dapsen, daprec and daprel. You link these routines into the host program by adding —idap to your compilation command. Note that they can be called fromthehost program either as subroutines or functions, but the only interface routine which returns a useful result when invoked as a function is dapcon. In FORTRAN, you should invoke dapoonas a function, and declare itas integer dapcon.

Formal specifications for the FORTRAN and C routines are given in appendix E, starting on page 161.

Figure 3.1 opposite shows the communication that takes place between the DAP program and the host program.

Before a DOE file can be executed by the DAP it has to be loaded into the DAP code store. You carry out this loading process by a call to dapcon (DAP, connect) in your host program.

dapcon is the first interface routine call to be issued by the host program. It is an integer function and takes one argument

— the name of the file containing the DOE version of the program to be loaded. The usual form of the argument is the name of the DOE file given as a literal.

For example, in a FORTRAN host program you might issue:

result = dapconC’ DOF-file-name’) or in aC program:

result = dapcon (“DOF-file-name”);

The DOE file will direct dapcon to the hardware or to the simulator, whichever you specified in your call to dapopt. It you have not called dapopt, the default action is to run on the hardware. For more details of dapopt, see section 3.4, on page 42.

If in dapopt you specified your DAP program was to be run on the simulator, dapcon will load your program immediately.

If you specified DAP hardware, then loading might not take place immediately. Several programs can be loaded into the DAP at the sametime;if there is not enough space to load a new program into the DAP, the following message appears on the host screen:

the program will be put in a queue, and dapcon will wait until there is a large enough slot in the DAP to load the program.

running on the simulator

running on DAP hardware

[

Awaiting DP resources

DAP Series: Program Development under UNIX manOQ3.04 37

For more details of multi-programming on the DAF see chapter 7, which starts on page 127.

Once your program is loaded into the DAP, dapcon returns control to your host program, which continues executing.

dapcon returns an integer value in the range 0 to 5:

Result returned Meaning of result from dapcon

0 Success

1 Unable to open DOE file

2 Unable to read DOE file

3 NotaDOFfile

4 Unable to open channel to hardware DAP

5 DAP load failed

daprel You should calldaprel(DAP, release) from the host program when all DAP processing and communication has been completed. daprel should therefore always be the last DAP interface subroutine that you call from the host; it frees the DAP so that other users can access it.

arguments to daprel daprel takes no arguments.

daprel is called automatically if the host program terminates or if you issue a second call to dapcon in your host program without an intervening call to daprel. (In this case daprel is first called automatically, then your second dapcon is acted on). If you issue a call to daprel when the DAP is not connected, the call is ignored.

3.2.2

dapsen

and

daprec The interface subroutines dapsen (DAP, send to) and daprec (DAP, receive from) are used for the transfer of data between the host program and the DAP program.

dapsen sends data from the host program to the DAP program and daprec receives data from the DAP program into the host program. The use of the arguments for these two subroutines is identical, only the direction of transfer changes.

arguments to dapsen and Each subroutine takes three arguments:

daprec

. The name of a FORTRAN-PLUS conon block (or of an APAL data section with the host, coxmnon and write name of DAP common block properties) to or from which the data is to be sent.

start location of data to be • The name of a word-aligned data area in the host transferred program (in FORTRAN programs), or the address of such an area

(

in C programs), identifying the start location of the block of data to be transferred.

In a FORTRAN host program In a FORTRAN host program the normal choice for this argument is the name of the first item in a coon block, because it will always be word-aligned. Character variables and arrays require special treatment when being transferred. Before you give the name of a

38 man003.04 AMT

3.3: Example 39

character variable or array as the second argument to dapsen or daprec you should equivalence the character variable with an integer variable, which will make sure that the object is word-aligned. For a formal specification of the FORTRAN language interface see section E.2 on page 162.

In a C host program In aC host program this argument should be the address of a word-aligned variable or array. If the address is not word-aligned it should be unioned to a word-aligned variable or placed in a word-aligned structure. AMI recommends that all character and short variables and arrays to be transferred to and from the DAP are actually or effectively word-aligned in this way. For a formal specification of the C language interface see section E.1 on page 161.

number of DAP words to be • An integer constant (or the name of an integer variable)

transferred which specifies the size of the data block to be

transferred, in units of DAP words (a DAP word contains 32 bits)

The examples of host programs in figures 3.3 and 3.4 illustrate the use of daprec and dapsen.

Note: In your DAP program, before you use data transferred from the host, you have to call the FORTRAN-PLUS mode conversion routine convhtod. Similarly, if you are going to transfer data back to the host, before you leave the DAP program, you have to call convdtoh. For more details, see [2], DAP Series: FORTRAN-PLUS enhanced.

You can make any number of dapsen and daprec calls between a dapcon and a daprel call in a host program.

3.2.3 dapent You transfer control from the host program to the DAP by a call to dapent (DAP, enter).

argumentstodapent dapent takes one argument ^— the name of the FORTRAN-PLUS entry subroutine for APAL code section or entry point with the host property) which is to be executed. Once the DAP program is running, execution of the host program is suspended until a return instruction in the DAP entry subroutine is obeyed. At this point the host program will start again, at the instruction immediately after the call to dapent.

3.3 Example

The following is a simple example of a complete FORTRAN-PLUS program, with examples of suitable host programs, one written in FORTRAN, and one in C. The example shows how to compile and run the program on the DAP hardware and on the simulator.

DAP Series: Program Development under UNIX manOQ3.04 39

3.3.1 The DAP program

This example can be run on a DAP 500 or DAP 600 machine.

You should set the environment variable DPSIZE to the correct value for your target DAP before running dapf (for more details of DAPSIZE see section 2.1 on page 7).

Each of the two host programs initialises an array of numbers, transfers them to the DAP, which sums all the components and returns the total to the host. The example is intended to illustrate compiling and running DAP programs and host-DAP communications: it is not intended to represent an efficient use of the DAR

The DAP program is shown in figure 3.2 below.

entry subroutine dapentry

parameter fNROWS = 40, NCOLS = 70) integer*4 frif*ws *NCOLS)

integer*4 isum common /indata/ in common /outdata/ isum C

C Convert input data from host mode to matrix mode C

call convhtod fin) C

C Calculate sum of matrix components C

isum = sumfin) C

C Convert result from scalar mode to host mode C

call convdtoh fisum) C

C Return control to the host program C

return end

Figure 3.2 Example DAP program

The FORTRAN-PLUS code is compiled using the dapf command:

[

^dapf -o dapprog dapprog.df

which compiles dapprog. df and generates the DOE file dapprog.

3.3.2 Compiling the FORTRAN

The FORTRAN host program is compiled using the f77

host program

^command:

[

^{f77 -o hostprog hostprog.f -ldap}

40 manQO3.04 AMT

3.3: Example 47

which compiles hostprog. f and generates the executable filehostprog. The program is listed in figure 3.3 below.

program hostprog

parameter (NBDWS 40, NCOLS ⁼ 70) integer in (NROWS,NCOLS)

integer isuin

integer i, j, ires, dapcon common /indata/ in

common /outdata/ isum C

C Initialise input data C

C Load DP program C

ires dapcon(’dapprog’) if (ires.ne.0) then

write(0,1000) ires

1000 format(//’dapcon call failed (reason = ‘, i5, ‘)‘/) stop

endif C

C Transfer input data to the DP C

call dapsenf’indata’, in, NROWS*NCOLS) C

C Execute DAP program C

call dapent(’dapentry’) C

C Transfer result back from DAP and release DAP resource C

call daprec(’outdata’, isum, 1) call daprel

C

C Display result C

write(6,2000) isum

2000 formatf//’Sum of matrix is ‘, ±8/) stop

end

Figure 3.3 Example FORTRAN host program

DAP Series: Program Development under UNIX manQQ3.04 47

3.3.3 Compiling the C host program

The C host program is compiled using the cc command:

[

^{-o hostprog hostprog.c}

which compileshostprog.c and generatestheexecutable file hostprog. The program is listed in figure 3.4 on the page opposite.

3.3.4 Running the program

The host program isnowexecuted in the usual way, by typing:

hostprog

The DAP program will be loaded into the DAP hardware (by dapcon)and data sent to the DAP (by dapsen). Control is then passed to the DAP (by dapent), and after the DAP processing is complete, control is returned to the host program and the result is returned to the host (by daprec).

The DAP space used by this program is then released (by daprel), so that other users can access it, and the host post-processing starts. In this case the post-processing is simply a display of the result.

If dapcon fails to connect to the DAP it will return an error code, the host program will print the value of the code, and will stop. Appendix E on page 162 lists the meanings of the six possible dapcon return codes.

If you want to run the program on the simulator instead of on the hardware, you would first issue the dapopt command using the —si flag:

Dans le document Series DAP (Page 47-52)