AmigaOS Manual: AmigaDOS Using Scripts - Revision history

Steven Solie: /* Automatic Scripts */

2014-03-13T16:57:48Z

Automatic Scripts

← Older revision		Revision as of 16:57, 13 March 2014
Line 44:		Line 44:
	You can automatically generate scripts using the LIST command. LIST has an LFORMAT option that allows you to modify its output to include any text you wish along with the usual LIST output. This text can be a command and command keywords, with the file name LISTed appearing as an argument to the command. If you list the contents of a directory this way, redirecting the output to a file, you have a ready-made script that applies a command to the contents of that directory.		You can automatically generate scripts using the LIST command. LIST has an LFORMAT option that allows you to modify its output to include any text you wish along with the usual LIST output. This text can be a command and command keywords, with the file name LISTed appearing as an argument to the command. If you list the contents of a directory this way, redirecting the output to a file, you have a ready-made script that applies a command to the contents of that directory.

	When an operation on multiple files is too involved ot be done with a single pattern matching command, use an automatically generated script to execute the command for each of the files. For example, an operation that renames a series of files, giving the current file names the same extension, cannot be done with a single pattern-matching RENAME. See the LIST section ~~in Chapter 6~~ for information on LIST's LFORMAT option ~~that~~ the ~~examples~~ in ~~Chapter 8~~ for an illustration of this technique.		When an operation on multiple files is too involved ot be done with a single pattern matching command, use an automatically generated script to execute the command for each of the files. For example, an operation that renames a series of files, giving the current file names the same extension, cannot be done with a single pattern-matching RENAME. See the [[AmigaOS_Manual:_AmigaDOS_Command_Reference#LIST\|LIST section]] for information on LIST's LFORMAT option and the [[AmigaOS_Manual:_AmigaDOS_Command_Examples\|AmigaDOS command examples]] for an illustration of this technique.

	= Special Script Characters =		= Special Script Characters =

Steven Solie: /* Understanding Scripts */

2014-03-13T16:54:32Z

Understanding Scripts

← Older revision		Revision as of 16:54, 13 March 2014
Line 24:		Line 24:
	{{Note\|You can avoid having to use the EXECUTE command and the full path by setting the script's s protection bit. Enter the command PROTECT <script> +s, substituting the path to the script. When the s bit is set, enter only the name of the script to execute it.}}		{{Note\|You can avoid having to use the EXECUTE command and the full path by setting the script's s protection bit. Enter the command PROTECT <script> +s, substituting the path to the script. When the s bit is set, enter only the name of the script to execute it.}}

	It is possible to run a script that has a Workbench project icon by using the ICONX command as the default tool. ~~For~~ more information on the ICONX command~~, see Chapter 6~~.		It is possible to run a script that has a Workbench project icon by using the ICONX command as the default tool. See [[AmigaOS_Manual:_AmigaDOS_Command_Reference#ICONX\|ICONX]] for more information on the ICONX command.

	== Kinds of Scripts ==		== Kinds of Scripts ==

	There are several kinds of scripts that you can use on the Amiga, including scripts of AmigaDOS commands, scripts of ARexx commands, and scripts of ED commands. For details on writing ARexx scripts, see the ARexx User's Guide. See the ED section ~~of Chapter 4~~ for information on ED command scripts.		There are several kinds of scripts that you can use on the Amiga, including scripts of AmigaDOS commands, scripts of ARexx commands, and scripts of ED commands. For details on writing ARexx scripts, see the ARexx User's Guide. See the [[AmigaOS_Manual:_AmigaDOS_Using_the_Editors#ED\|ED section]] for information on ED command scripts.

	=== When to Use ARexx ===		=== When to Use ARexx ===

	You can create both AmigaDOS and ARexx scripts on the Amiga. These scripts are not mutually exclusive; ~~under AmigaDOS Release 2 and beyond,~~ ARexx commands can appear in AmigaDOS scripts and vice versa. However, different tasks are appropriate to each.		You can create both AmigaDOS and ARexx scripts on the Amiga. These scripts are not mutually exclusive; ARexx commands can appear in AmigaDOS scripts and vice versa. However, different tasks are appropriate to each.

	Unlike ARexx, AmigaDOS is not a general purpose programming language. AmigaDOS is oriented toward basic file management and system configuration tasks. ARexx is meant to be used for accomplishing tasks more complex than simple branching and conditional execution.		Unlike ARexx, AmigaDOS is not a general purpose programming language. AmigaDOS is oriented toward basic file management and system configuration tasks. ARexx is meant to be used for accomplishing tasks more complex than simple branching and conditional execution.

Steven Solie at 16:50, 13 March 2014

2014-03-13T16:50:05Z

← Older revision		Revision as of 16:50, 13 March 2014
Line 86:		Line 86:
	== Double Dollar (<$$>) ==		== Double Dollar (<$$>) ==

	A bracketed double dollar sign (<$$>) substitutes the current process number. You can reference the current Shell number by the double dollar sign character string <$$> including brackets since it always returns the current process number as a string. When you create temporary files in a multitasking environment, it is essential for these files to have unique names so that processes do not interfere with each other. Adding the <$$> string to file names creates unique names for temporary files, logical assignments, and PIPEs. A .KEY statement is required in any script that uses <$$>. .KEY is described on ~~page 5-7~~. To avoid conflict with the redirection arguments, <$$>'s angle brackets can be redefined using the .BRA and .KET commands. .BRA and .KET are described ~~on page~~ ~~5-8~~.		A bracketed double dollar sign (<$$>) substitutes the current process number. You can reference the current Shell number by the double dollar sign character string <$$> including brackets since it always returns the current process number as a string. When you create temporary files in a multitasking environment, it is essential for these files to have unique names so that processes do not interfere with each other. Adding the <$$> string to file names creates unique names for temporary files, logical assignments, and PIPEs. A .KEY statement is required in any script that uses <$$>. .KEY is described [[#Dot Commands\|below]]. To avoid conflict with the redirection arguments, <$$>'s angle brackets can be redefined using the .BRA and .KET commands. .BRA and .KET are described [[#Dot Commands\|below]].

	== Question Mark (?) ==		== Question Mark (?) ==

Steven Solie: /* Substitution */

2014-03-13T14:56:20Z

Substitution

← Older revision		Revision as of 14:56, 13 March 2014
Line 187:		Line 187:
	For example, the following script called Demo uses these lines:		For example, the following script called Demo uses these lines:

	. KEY filename		.KEY filename
	ECHO "This line does NOT print <angle> brackets."		ECHO "This line does NOT print <angle> brackets."
	. BRA {		.BRA {
	. KET }		.KET }
	ECHO "This line DOES print <angle> brackets."		ECHO "This line DOES print <angle> brackets."
	ECHO "The specified filename is (filename)."		ECHO "The specified filename is (filename)."

Steven Solie: /* Allowing Arguments */

2014-03-13T14:55:35Z

Allowing Arguments

← Older revision		Revision as of 14:55, 13 March 2014
Line 171:		Line 171:
	The .KEY (or .K) keyword specifies both keyword names and positions in the command line. It teills EXECUTE the number of parameters and how to interpret them. Only one .KEY statement is allowed per script; if present, it should be the first line in the file. Any script containing <$$> must also contain a .KEY statement.		The .KEY (or .K) keyword specifies both keyword names and positions in the command line. It teills EXECUTE the number of parameters and how to interpret them. Only one .KEY statement is allowed per script; if present, it should be the first line in the file. Any script containing <$$> must also contain a .KEY statement.

	The arguments on the .KEY line can be given with the /A and /K directives, which work the same as in an AmigaDOS template. (Templates ~~are~~ ~~described~~ in ~~Chapter~~ 6.) Arguments followed by /A are required; arguments followed by /K require the name of that argument as a keyword. Use commas to separate multiple arguments in the .KEY line, not spaces.		The arguments on the .KEY line can be given with the /A and /K directives, which work the same as in an AmigaDOS template. See [[AmigaOS_Manual:_AmigaDOS_Command_Reference#Template\|Templates]] for all the options available. Arguments followed by /A are required; arguments followed by /K require the name of that argument as a keyword. Use commas to separate multiple arguments in the .KEY line, not spaces.

	For example, if a script starts with .KEY filename/A it indicates that a file name must be given on the EXECUTE command line after the name of the script. This file name is substituted in subsequent lines of the script. For example, if you have a script called Newtext and the first line is:		For example, if a script starts with .KEY filename/A it indicates that a file name must be given on the EXECUTE command line after the name of the script. This file name is substituted in subsequent lines of the script. For example, if you have a script called Newtext and the first line is:

Steven Solie: /* Allowing Arguments */

2014-03-13T14:51:31Z

Allowing Arguments

← Older revision		Revision as of 14:51, 13 March 2014
Line 175:		Line 175:
	For example, if a script starts with .KEY filename/A it indicates that a file name must be given on the EXECUTE command line after the name of the script. This file name is substituted in subsequent lines of the script. For example, if you have a script called Newtext and the first line is:		For example, if a script starts with .KEY filename/A it indicates that a file name must be given on the EXECUTE command line after the name of the script. This file name is substituted in subsequent lines of the script. For example, if you have a script called Newtext and the first line is:

	.KEY filename/A, TO/K		.KEY filename/A,TO/K

	you must specify a file name variable. The TO variable is optional, but, if specified, the TO keyword must be used. The following is an acceptable way to run Newtext:		you must specify a file name variable. The TO variable is optional, but, if specified, the TO keyword must be used. The following is an acceptable way to run Newtext:

Steven Solie: /* Dot Commands */

2014-03-13T14:51:08Z

Dot Commands

← Older revision		Revision as of 14:51, 13 March 2014
Line 148:		Line 148:
	! Dot Command !! Meaning		! Dot Command !! Meaning
	\|-		\|-
	\| .KEY \|\| Argument template used to specify the format of arguments; can be abbreviated to .K. Separate arguments for .KEY with commas. Do not use spaces. See ~~page~~ ~~5-7~~ ~~for~~ more information on using .KEY.		\| .KEY \|\| Argument template used to specify the format of arguments; can be abbreviated to .K. Separate arguments for .KEY with commas. Do not use spaces. See [[#Allowing Arguments\|Allowing Arguments]] more information on using .KEY.
	\|-		\|-
	\| .DOT <ch> \|\| Change dot character from . to <ch>, where <ch> is the character that is substituted.		\| .DOT <ch> \|\| Change dot character from . to <ch>, where <ch> is the character that is substituted.

Steven Solie: /* Debugging Script Files */

2014-01-28T19:40:31Z

Debugging Script Files

← Older revision		Revision as of 19:40, 28 January 2014
Line 379:		Line 379:

	Inserting the line SET ECHO ON within the script assists in locating errors. This causes all subsequent command lines to be ECHOed to the screen as they are executed. Error messages are printed after the system tries to execute the incorrect command. To disable SET ECHO, enter SET ECHO OFF or delete the SET ECHO ON line.		Inserting the line SET ECHO ON within the script assists in locating errors. This causes all subsequent command lines to be ECHOed to the screen as they are executed. Error messages are printed after the system tries to execute the incorrect command. To disable SET ECHO, enter SET ECHO OFF or delete the SET ECHO ON line.

			= Using Environment Variables =

			Environment variables are used in scripts to hold status and string information. Variables can be substituted for strings that are long and tedious to enter. Changing the value of the variable is more convenient that re-editing the script when the value for the string changes.

			Environment variables are maintained by AmigaDOS rather than individual applications. These variables can be accessed and used by different programs or scripts. When a variable name preceded by a dollar sign ($) is encountered in a script, the variable name is replaced by the value assigned to the variable. The line is then executed as if you had originally entered the value.

			For example, AmigaDOS maintains the variables Workbench and Kickstart that track the current version numbers of your Workbench and Kickstart software. Running the following line prints the Workbench version number.

			ECHO "Amiga Workbench Disk. Release Version $Workbench"

			Some variables, such as the Workbench and Kickstart variables, have already been created. The Shell responds to the ECHO variable and maintains the PROCESS, RC, and RESULT2 local variables automatically. These are explained as follows:

			{\| class="wikitable"
			\| ECHO \|\| When the value of this variable is ON, commands are echoed to the screen when they are executed. When it is OFF (the default), commands are not echoed.
			\|-
			\| PROCESS \|\| Holds the process (CLI) number.
			\|-
			\| RC \|\| Holds the condition flag return code of the last command executed (0, 5, 10, or 20). This is often used in scripts.
			\|-
			\| RESULT2 \|\| Holds the secondary return code, or error number, that explains why a command failed.
			\|}

			For example, if you include the SET ECHO ON command at the beginning of a script, each line of the script is echoed to the screen as it is executed.

			When an environment variable is given a numeric value, it can be used in calculations and expressions. For example, if you assign the value 9 to a variable called nine, $nine in EVAL expressions. For example:

			1> SETENV nine 9
			1> EVAL 5 * $nine
			45

			EVAL is an AmigaDOS command that evaluates integer and Boolean expressions. However, it does not work on environment variables that have a fractional numeric value; be sure to use whole numbers when using EVAL.

			=== Creating Environment Variables ===

			Environment variables can be created with the SET and SETENV commands.

			==== SET ====

			SET creates local variables, which are recognized only by the Shell in which they are created and any Shells created by that original Shell. For example, if you are creating an environment variable in your Shell window, then execute the NEWSHELL command through the Execute Command menu item, the new Shell does not recognize any of the variables created in your original Shell. However, if you open a second Shell by entering the NEWSHELL command in your original Shell, the new Shell recognizes any variables created in its parent Shell.

			Using the GET command displays the value associated with a variable; using the UNSET command removes variables.

			==== SETENV ====

			SETENV creates global variables recognized by all Shells. Global variables are stored as small ASCII files in the ENV: directory. GETENV displays the value associated with global variables and UNSETENV removes global variables. Use global variables only when certain values must be available to other processes.

			Some applications use environment variables. For example, the MORE program supports an Editor environment variable. You can use SETENV to specify MEmacs as your editor of choice:

			1> SETENV Editor Extras:Tools/MEmacs

			Be sure to specify the complete path to MEmacs.

			If you use MORE to view the contents of the User-startup file, pressing Shift+E automatically transfers to a MEmacs screen with the User-startup loaded and ready for editing.

Steven Solie: /* Ending a Script */

2014-01-28T19:36:51Z

Ending a Script

← Older revision		Revision as of 19:36, 28 January 2014
Line 327:		Line 327:

	In general, scripts end when they have completed all the specified commands. Return codes report whether executed commands succeeded or failed. You can include a QUIT command in a script to end it, but unless there is a specific condition under which you wish the script to end, including QUIT is not necessary. You can stop a script by pressing Ctrl+D in the window in which it is running.		In general, scripts end when they have completed all the specified commands. Return codes report whether executed commands succeeded or failed. You can include a QUIT command in a script to end it, but unless there is a specific condition under which you wish the script to end, including QUIT is not necessary. You can stop a script by pressing Ctrl+D in the window in which it is running.

			= Condition Flags =

			Conditions flags indicate the condition upon which a particular command stops running. Then commands are executed, return codes report if they succeeded or failed. The standard return codes are:

			{\| class="wikitable"
			\| 0 \|\| The command succeeded.
			\|-
			\| 5 \|\| Represents a caution, usually indicating that some type of error occurred. The error, however, was not serious enough to abort the command. If the command is part of a script, subsequent commands are executed. Several commands set the condition flag to WARN to specify a non-error command outcome.
			\|-
			\| 10 \|\| Represents an error. A return code of 10 aborts a script, unless a higher limit has been set with the FAILAT command.
			\|-
			\| 20 \|\| Represents a failure.
			\|}

			Other values may be returned by applications. In such cases, the previously listed values are considered lower limits of the specified condition as follows:

			{\| class="wikitable"
			\| 0-4 \|\| No Error
			\|-
			\| 5-9 \|\| Warn
			\|-
			\| 10-19 \|\| Error
			\|-
			\| 20 or above \|\| Failure
			\|}

			Some commands, such as ASK and SEARCH, use the WARN flag to signal certain conditions for testing in scripts.

			For example, in the COPY script on page 5-12, the ASK command requests confirmation to continue the copy:

			ASK "Continue Copy?"
			IF WARN
			COPY 3a.eps DF0:

			Pressing y sets the condition flag to 5 (WARN), executing the IF block. Pressing N or Return sets the condition flag to 0 (NO ERROR), aborting the script because the IF statement did not receive the specified return code.

			= Debugging Script Files =

			If a script command fails, you may see one of the following error messages:

			Unknown command <command>

			This occurs when you have entered a command that is unrecognizable.

			<command> failed returncode 20

			This occurs when a valid command's arguments are entered incorrectly. Enter WHY at the prompt after the error appears for more information about the error.

			If an error appears, use your text editor (ED, MEmacs or a word processor that can save ASCII files) to correct the line containing that command.

			Inserting the line SET ECHO ON within the script assists in locating errors. This causes all subsequent command lines to be ECHOed to the screen as they are executed. Error messages are printed after the system tries to execute the incorrect command. To disable SET ECHO, enter SET ECHO OFF or delete the SET ECHO ON line.

Steven Solie: /* Dot Commands */

2014-01-28T19:33:29Z

Dot Commands

Show changes