Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "AmigaOS Manual: ARexx Input and Output"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
m
m
 
(36 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
The external data stack is ARexx's queue service. An ARexx program can store character strings (lines) to the stack and pull strings out of the stack. The external data stack is connected to the command line interface which is the standard input/output stream. The external data stack provides an alternative way for inter-process-communication, since a parent program can pull lines from the stack which where pushed there by a child program and a child program can pull lines from the stack which were pushed there by a parent program.
 
The external data stack is ARexx's queue service. An ARexx program can store character strings (lines) to the stack and pull strings out of the stack. The external data stack is connected to the command line interface which is the standard input/output stream. The external data stack provides an alternative way for inter-process-communication, since a parent program can pull lines from the stack which where pushed there by a child program and a child program can pull lines from the stack which were pushed there by a parent program.
   
There are two instructions for adding lines of text to the external data stack. PUSH will add one line at the top of the stack while QUEUE will add the line at the bottom of the stack. Despite of the stack's connection to the standard input/output stream, lines stored in the external data stack will not be visible to the user until an ARexx script exits. Only after then the whole content of the stack will be emptied to the standard output stream.
+
There are two instructions for adding lines of text to the external data stack. [[AmigaOS_Manual:_ARexx_Instructions#PUSH|PUSH]] will add one line at the top of the stack while [[AmigaOS_Manual:_ARexx_Instructions#QUEUE|QUEUE]] will add the line at the bottom of the stack. Despite of the stack's connection to the standard input/output stream, lines stored in the external data stack will not be visible to the user until an ARexx script exits. Only after then the whole content of the stack will be emptied to the standard output stream.
   
PULL instruction is used for reading and removing the top-most line from the external data stack. If the stack is empty, PULL will read a line from the standard input stream, i.e. from the console window.
+
[[AmigaOS_Manual:_ARexx_Instructions#PULL|PULL]] instruction is used for reading and removing the top-most line from the external data stack. If the stack is empty, [[AmigaOS_Manual:_ARexx_Instructions#PULL|PULL]] will read a line from the standard input stream, i.e. from the console window.
   
== Program x. ReadLine.rexx ==
+
== Program 17. ReadLine.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/*
 
/*
Line 24: Line 24:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
The external data stack can operate as a stack or a queue, depending on which instruction has been used for filling the stack: PUSH or QUEUE.
+
The external data stack can operate as a stack or a queue, depending on which instruction has been used for filling the stack: [[AmigaOS_Manual:_ARexx_Instructions#PUSH|PUSH]] or [[AmigaOS_Manual:_ARexx_Instructions#QUEUE|QUEUE]].
   
When a PUSH instruction is used for adding a line to the stack, the line will be added at the top of the stack. Together with a PULL instruction this forms a stack data structure where last inserted line is pulled out first - last-in-first-out (LIFO).
+
When a [[AmigaOS_Manual:_ARexx_Instructions#PUSH|PUSH]] instruction is used for adding a line to the stack, the line will be added at the top of the stack. Together with a [[AmigaOS_Manual:_ARexx_Instructions#PULL|PULL]] instruction this forms a stack data structure where last inserted line is pulled out first last-in-first-out (LIFO).
   
== Program x. Stack.rexx ==
+
== Program 18. Stack.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/*
 
/*
Line 48: Line 48:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
If a QUEUE instruction is used for adding a line to the stack, the line will be added at the bottom of the stack. Together with a PULL instruction this forms a queue data structure where the first inserted line is pulled out first - first-in-first-out (FIFO).
+
If a [[AmigaOS_Manual:_ARexx_Instructions#QUEUE|QUEUE]] instruction is used for adding a line to the stack, the line will be added at the bottom of the stack. Together with a [[AmigaOS_Manual:_ARexx_Instructions#PULL|PULL]] instruction this forms a queue data structure where the first inserted line is pulled out first first-in-first-out (FIFO).
   
== Program x. Queue.rexx ==
+
== Program 19. Queue.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/*
 
/*
Line 70: Line 70:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
If the number of stacked items is unknown, you can use LINES function to find out how many lines there currently are in the stack. The program below demonstrates how to empty the stack by utilising the LINES function.
+
If the number of stacked items is unknown, you can use [[AmigaOS_Manual:_ARexx_Functions#LINES.28.29|LINES]] function to find out how many lines there currently are in the stack. The program below demonstrates how to empty the stack by utilising the [[AmigaOS_Manual:_ARexx_Functions#LINES.28.29|LINES]] function.
   
== Program x. EmptyStack.rexx ==
+
== Program 20. EmptyStack.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/*
 
/*
Line 94: Line 94:
 
An example of inter-process-communication through the external data stack.
 
An example of inter-process-communication through the external data stack.
   
=== Program x. Parent.rexx ===
+
=== Program 21. Parent.rexx ===
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/*
 
/*
Line 114: Line 114:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
=== Program x. Child.rexx ===
+
=== Program 22. Child.rexx ===
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/*
 
/*
Line 135: Line 135:
 
The character input and output streams are used for reading and writing to files. The following functions are available for the streams:
 
The character input and output streams are used for reading and writing to files. The following functions are available for the streams:
   
  +
{| class="wikitable"
CLOSE Close an input/output stream.
 
  +
|-
EOF Check if the read/write position of the stream is at the end of the stream.
 
OPEN Open an input/output stream.
+
| [[AmigaOS_Manual:_ARexx_Functions#CLOSE.28.29|CLOSE]] || Close an input/output stream.
  +
|-
READCH Reads specified number of characters from a previously opened input stream at the current stream position.
 
  +
| [[AmigaOS_Manual:_ARexx_Functions#EOF.28.29|EOF]] || Check if the read/write position of the stream is at the end of the stream.
READLN Reads a line from a previously opened input stream at the current stream position.
 
  +
|-
SEEK Moves the stream's read/write position.
 
  +
| [[AmigaOS_Manual:_ARexx_Functions#OPEN.28.29|OPEN]] || Open an input/output stream.
WRITECH Writes a string to a previously opened output stream at the current stream position.
 
  +
|-
WRITELN Writes a line to a previously opened output stream at the current stream position.
 
  +
| [[AmigaOS_Manual:_ARexx_Functions#READCH.28.29|READCH]] || Reads specified number of characters from a previously opened input stream at the current stream position.
  +
|-
  +
| [[AmigaOS_Manual:_ARexx_Functions#READLN.28.29|READLN]] || Reads a line from a previously opened input stream at the current stream position.
  +
|-
  +
| [[AmigaOS_Manual:_ARexx_Functions#SEEK.28.29|SEEK]] || Moves the stream's read/write position.
  +
|-
  +
| [[AmigaOS_Manual:_ARexx_Functions#WRITECH.28.29|WRITECH]] ||Writes a string to a previously opened output stream at the current stream position.
  +
|-
  +
| [[AmigaOS_Manual:_ARexx_Functions#WRITELN.28.29|WRITELN]] || Writes a line to a previously opened output stream at the current stream position.
  +
|}
   
 
The general procedure of writing to a file is as follows:
 
The general procedure of writing to a file is as follows:
   
# Open an output stream using OPEN function.
+
# Open an output stream using [[AmigaOS_Manual:_ARexx_Functions#OPEN.28.29|OPEN]] function.
# Write to the stream using WRITECH or WRITELN function.
+
# Write to the stream using [[AmigaOS_Manual:_ARexx_Functions#WRITECH.28.29|WRITECH]] or [[AmigaOS_Manual:_ARexx_Functions#WRITELN.28.29|WRITELN]] function.
# Close the stream using CLOSE function.
+
# Close the stream using [[AmigaOS_Manual:_ARexx_Functions#CLOSE.28.29|CLOSE]] function.
   
== Example x. CreateFile.rexx ==
+
== Example 23. CreateFile.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/* Create a file */
 
/* Create a file */
Line 174: Line 184:
 
The general procedure of reading from a file is as follows:
 
The general procedure of reading from a file is as follows:
   
# Open an input stream using OPEN function.
+
# Open an input stream using [[AmigaOS_Manual:_ARexx_Functions#OPEN.28.29|OPEN]] function.
# Read characters or lines from the stream using READCH or READLN function.
+
# Read characters or lines from the stream using [[AmigaOS_Manual:_ARexx_Functions#READCH.28.29|READCH]] or [[AmigaOS_Manual:_ARexx_Functions#READLN.28.29|READLN]] function.
# Close the stream using CLOSE function.
+
# Close the stream using [[AmigaOS_Manual:_ARexx_Functions#CLOSE.28.29|CLOSE]] function.
   
== Example x. ReadFile.rexx ==
+
== Example 24. ReadFile.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/* Read a file */
 
/* Read a file */
Line 199: Line 209:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
The character input and output stream functions can also be used for reading and writing to the standard input and output stream - to the console window. ARexx opens and closes the input and output streams to the standard input and output automatically and provides a common logical name for accessing the standard input/output stream: STDIN.
+
The character input and output stream functions can also be used for reading and writing to the standard input and output stream to the console window. ARexx opens and closes the input and output streams to the standard input and output automatically and provides a common logical name for accessing the standard input/output stream: [[AmigaOS_Manual:_ARexx_Special_Variables|STDIN]].
   
Reading and writing to the console window is simpler than reading and writing to a file because you do not have to open and close the stream - ARexx will do that for you. To read a line from the console window you just call the READLN function with the logical name of STDIN:
+
Reading and writing to the console window is simpler than reading and writing to a file because you do not have to open and close the stream ARexx will do that for you. To read a line from the console window you just call the [[AmigaOS_Manual:_ARexx_Functions#READLN.28.29|READLN]] function with the logical name of [[AmigaOS_Manual:_ARexx_Special_Variables|STDIN]]:
  +
<syntaxhighlight lang="rexx">
 
line = READLN( STDIN )
+
line = READLN( STDIN )
  +
</syntaxhighlight>
   
 
Writing to the console window is equally easy:
 
Writing to the console window is equally easy:
  +
<syntaxhighlight lang="rexx">
  +
CALL WRITELN( STDIN, 'Hello world!' )
  +
</syntaxhighlight>
   
  +
The advantage of using the input/output functions over [[AmigaOS_Manual:_ARexx_Instructions#SAY|SAY]] and [[AmigaOS_Manual:_ARexx_Instructions#PULL|PULL]] instructions is that you can read and write restricted number of characters to the console instead of lines.
CALL WRITELN( STDIN, 'Hello world!' )
 
 
The advantage of using the input/output functions over SAY and PULL instructions is that you can read and write restricted number of characters to the console instead of lines.
 
   
== Example x. ReadCharacters.rexx ==
+
== Example 25. ReadCharacters.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/* Read 3 characters from the standard input */
 
/* Read 3 characters from the standard input */
Line 225: Line 237:
 
The following program shows how to print text without changing a line.
 
The following program shows how to print text without changing a line.
   
== Example x. WriteCharacters.rexx ==
+
== Example 26. WriteCharacters.rexx ==
 
<syntaxhighlight lang="rexx">
 
<syntaxhighlight lang="rexx">
 
/* Print prompt using WRITECH */
 
/* Print prompt using WRITECH */
CALL WRITECH( STDIN, "Hi! I'm Amiga. What is your problem? " )
+
CALL WRITECH( STDIN, "Hi! I'm Amiza. What is your problem? " )
   
 
PARSE PULL line
 
PARSE PULL line

Latest revision as of 14:16, 27 March 2019

ARexx's input and output model consists of three parts: character input streams, character output streams, and an external data stack. The input and output streams can be manipulated character-by-character or line-by-line, while the data stack can be accessed only by line operations.

The External Data Stack

The external data stack is ARexx's queue service. An ARexx program can store character strings (lines) to the stack and pull strings out of the stack. The external data stack is connected to the command line interface which is the standard input/output stream. The external data stack provides an alternative way for inter-process-communication, since a parent program can pull lines from the stack which where pushed there by a child program and a child program can pull lines from the stack which were pushed there by a parent program.

There are two instructions for adding lines of text to the external data stack. PUSH will add one line at the top of the stack while QUEUE will add the line at the bottom of the stack. Despite of the stack's connection to the standard input/output stream, lines stored in the external data stack will not be visible to the user until an ARexx script exits. Only after then the whole content of the stack will be emptied to the standard output stream.

PULL instruction is used for reading and removing the top-most line from the external data stack. If the stack is empty, PULL will read a line from the standard input stream, i.e. from the console window.

Program 17. ReadLine.rexx

/* 
** Read a line from the console window. 
*/
SAY 'Type anything and press enter.'
 
/* 
** PULL will read a line from the standard input since
** the external data stack is empty.                   
*/
PULL line
SAY 'You typed:' line

The external data stack can operate as a stack or a queue, depending on which instruction has been used for filling the stack: PUSH or QUEUE.

When a PUSH instruction is used for adding a line to the stack, the line will be added at the top of the stack. Together with a PULL instruction this forms a stack data structure where last inserted line is pulled out first – last-in-first-out (LIFO).

Program 18. Stack.rexx

/* 
** Stack example 
*/
/* Put 3 lines to the stack */
PUSH 'Item 1'
PUSH 'Item 2'
PUSH 'Item 3'
 
/* Pop 3 lines from the stack */
PARSE PULL first
PARSE PULL second
PARSE PULL third
 
SAY '1st' first
SAY '2nd' second
SAY '3rd' third

If a QUEUE instruction is used for adding a line to the stack, the line will be added at the bottom of the stack. Together with a PULL instruction this forms a queue data structure where the first inserted line is pulled out first – first-in-first-out (FIFO).

Program 19. Queue.rexx

/* 
** Queue example 
*/
/* Put 3 lines to the stack */
QUEUE 'Item 1'
QUEUE 'Item 2'
QUEUE 'Item 3'
 
/* Pop 3 lines from the stack */
PARSE PULL first
PARSE PULL second
PARSE PULL third
 
SAY '1st' first
SAY '2nd' second
SAY '3rd' third

If the number of stacked items is unknown, you can use LINES function to find out how many lines there currently are in the stack. The program below demonstrates how to empty the stack by utilising the LINES function.

Program 20. EmptyStack.rexx

/*
** Empty the external data stack
*/
/* Add 4 lines to the external stack */
QUEUE 'Tinker, Tailor,'
QUEUE 'Soldier, Sailor,'
QUEUE 'Rich Man, Poor Man,'
QUEUE 'Beggar Man, Thief.'
 
/* Pull all lines from the stack */
DO LINES( STDIN )
    PARSE PULL line
    SAY line
END

Examples

An example of inter-process-communication through the external data stack.

Program 21. Parent.rexx

/* 
** This program adds data to the external stack, then
** executes the child program 'Child.rexx', which reads the data
** from the stack, and finally reads child's reply from the stack.
*/
/* Add two lines to the stack */
SAY 'Parent: sending data to child...'
QUEUE 'Item 1'
QUEUE 'Item 2'
 
/* Execute child */
ADDRESS command 'RX Child.rexx'
 
/* Get child's reply */
PARSE PULL message
SAY 'Parent: Got the following reply:' message

Program 22. Child.rexx

/* 
** Child program
*/
 
/* Get data */
PARSE PULL first
PARSE PULL second
SAY 'Child: Received the following data:'
SAY '     ' first
SAY '     ' second
 
/* Reply through the external stack */
PUSH 'Thanks!'

The Character Input and Output Streams

The character input and output streams are used for reading and writing to files. The following functions are available for the streams:

CLOSE Close an input/output stream.
EOF Check if the read/write position of the stream is at the end of the stream.
OPEN Open an input/output stream.
READCH Reads specified number of characters from a previously opened input stream at the current stream position.
READLN Reads a line from a previously opened input stream at the current stream position.
SEEK Moves the stream's read/write position.
WRITECH Writes a string to a previously opened output stream at the current stream position.
WRITELN Writes a line to a previously opened output stream at the current stream position.

The general procedure of writing to a file is as follows:

  1. Open an output stream using OPEN function.
  2. Write to the stream using WRITECH or WRITELN function.
  3. Close the stream using CLOSE function.

Example 23. CreateFile.rexx

/* Create a file */
file = 'RAM:myfile.txt'
 
/* Open a file for writing */
IF ~OPEN( 'MYFILE', file, 'W' ) THEN DO
    SAY 'Failed to create file "' || file || '".'
    EXIT 10
END
 
/* Write to the file */
CALL WRITELN( 'MYFILE', 'It goes in the morning on four feet,' )
CALL WRITELN( 'MYFILE', 'at lunch-time on two,' )
CALL WRITELN( 'MYFILE', 'in the evening on three.' )
CALL WRITELN( 'MYFILE', '' )
CALL WRITELN( 'MYFILE', 'What is it?' )
 
/* Close the file */
CALL CLOSE( 'MYFILE' )

The general procedure of reading from a file is as follows:

  1. Open an input stream using OPEN function.
  2. Read characters or lines from the stream using READCH or READLN function.
  3. Close the stream using CLOSE function.

Example 24. ReadFile.rexx

/* Read a file */
file = 'RAM:myfile.txt'
 
/* Open a file for reading */
IF ~OPEN( 'MYFILE', file, 'R' ) THEN DO
    SAY 'Failed to open file "' || file || '".'
    EXIT 10
END
 
/* Read the whole file content or maximum of 65535 characters */
content = READCH( 'MYFILE', 65535 )
 
/* Close the file */
CALL CLOSE( 'MYFILE' )
 
/* Print file content */
SAY content

The character input and output stream functions can also be used for reading and writing to the standard input and output stream – to the console window. ARexx opens and closes the input and output streams to the standard input and output automatically and provides a common logical name for accessing the standard input/output stream: STDIN.

Reading and writing to the console window is simpler than reading and writing to a file because you do not have to open and close the stream – ARexx will do that for you. To read a line from the console window you just call the READLN function with the logical name of STDIN:

line = READLN( STDIN )

Writing to the console window is equally easy:

CALL WRITELN( STDIN, 'Hello world!' )

The advantage of using the input/output functions over SAY and PULL instructions is that you can read and write restricted number of characters to the console instead of lines.

Example 25. ReadCharacters.rexx

/* Read 3 characters from the standard input */
characters = READCH( STDIN, 3 )
SAY characters
 
/* Any extra characters are stored in the     */
/* external data stack and can be pulled out. */
PARSE PULL extraChars
SAY extraChars

The following program shows how to print text without changing a line.

Example 26. WriteCharacters.rexx

/* Print prompt using WRITECH */
CALL WRITECH( STDIN, "Hi! I'm Amiza. What is your problem? " )
 
PARSE PULL line
SAY 'I see.'