1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
.TH GOLF 2gg $VERSION $DATE Development Tools
.SH NAME
write-file \- (files)
.SH PURPOSE
Write to a file.
.SH SYNTAX
.RS 4
.EX
write-file <file> | ( file-id <file id> ) \\
from <content> \\
[ length <length> ] \\
[ ( position <position> ) | ( append [ <append> ] ) ] \\
[ status <status> ]
.EE
.RE
.SH DESCRIPTION
.LP
.B WITHOUT FILE-ID
.LP
This is a simple method of writing a file. File named <file> is opened, data written, and file is closed. <file> can be a full path name, or a path relative to the application home directory (see \fBdirectories\fP).
write-file writes <content> to <file>. If "append" clause is used without boolean variable <append>, or if <append> evaluates to true, the <content> is appended to the file; otherwise the file is overwritten with <content>, unless "position" clause is used in which case file is not overwritten and <content> is written at byte <position> (with 0 being the first byte). Note that <position> can be beyond the end of file, in which case null-bytes are written between the current end of file and <position>.
File is created if it does not exist (even if "append" is used), unless "position" clause is used in which case file must exist.
If "length" is not used, then a whole string <content> is written to a file, and the number of bytes written is the length of that string. If "length" is specified, then exactly <length> bytes are written.
If "status" clause is used, then the number of bytes written is stored to <status>, unless error occurred, in which case <status> has the error code. The error code can be GG_ERR_POSITION (if <position> is negative or file does not support it), GG_ERR_WRITE (if there is an error writing file) or GG_ERR_OPEN if file cannot be open.
.LP
.B WITH FILE-ID
.LP
This method uses a <file id> that was created with \fBopen-file\fP. You can then write (and read) file using this <file id> and the file stays open until \fBclose-file\fP is called or the request ends.
If "position" clause is used, then data is written starting from byte <position>, otherwise writing starts from the current file position determined by the previous reads/writes or as set by using "set" clause in \fBfile-position\fP. After each read or write, the file position is advanced by the number of bytes read or written. Position can be set passed the last byte of the file, in which case writing will fill the space between the current end of file and the current position with null-bytes.
If "length" is not used, then a whole string is written to a file, and the number of bytes written is the length of that string. If "length" is specified, then exactly <length> bytes are written.
If "append" clause is used without boolean variable <append>, or if <append> evaluates to true, then file pointer is set at the end of file and data written.
If "status" clause is used, then the number of bytes written is stored to <status>, unless error occurred, in which case <status> has the error code. The error code can be GG_ERR_POSITION (if <position> is negative or file does not support it), GG_ERR_WRITE (if there is an error writing file) or GG_ERR_OPEN if file is not open.
.SH EXAMPLES
To overwrite file "/path/to/file" with "Hello World":
.RS 4
.EX
write-file "/path/to/file" from "Hello World"
.EE
.RE
To append "Hello World" to file:
.RS 4
.EX
set-string path="/path/to/file"
set-string cont="Hello World"
write-file path from cont append
.EE
.RE
To write only 5 bytes (i.e. "Hello") and get status (if successful, number "st" would be "5"):
.RS 4
.EX
set-string cont="Hello World"
write-file "file" from cont length 5 status st
.EE
.RE
To write a string "Hello" at byte position 3 in the existing "file":
.RS 4
.EX
set-string cont="Hello"
write-file "file" from cont position 3 status st
.EE
.RE
See \fBopen-file\fP for an example with "file-id" clause.
.SH SEE ALSO
Files
\fBchange-mode\fP
\fBclose-file\fP
\fBcopy-file\fP
\fBdelete-file\fP
\fBfile-position\fP
\fBfile-storage\fP
\fBfile-uploading\fP
\fBlock-file\fP
\fBopen-file\fP
\fBread-file\fP
\fBread-line\fP
\fBrename-file\fP
\fBstat-file\fP
\fBtemporary-file\fP
\fBuniq-file\fP
\fBunlock-file\fP
\fBwrite-file\fP
See all
\fBdocumentation\fP
|
