0
# Message Operations
1

2
Core functionality for creating, reading, writing, and managing GRIB/BUFR messages. This module provides the fundamental operations for message lifecycle management, file I/O, format detection, and memory handling.
3

4
## Capabilities
5

6
### Creating Messages from Files
7

8
Read messages from GRIB, BUFR, METAR, and GTS files with format-specific functions or automatic detection.
9

10
```python { .api }
11
def codes_new_from_file(fileobj, product_kind, headers_only=False):
12
    """
13
    Create a new message from file with explicit product type.
14
    
15
    Parameters:
16
    - fileobj: File object opened in binary mode
17
    - product_kind (int): Message type (CODES_PRODUCT_GRIB, CODES_PRODUCT_BUFR, etc.)
18
    - headers_only (bool): Read only headers if True
19
    
20
    Returns:
21
    int: Message handle ID or None if no more messages
22
    """
23

24
def codes_grib_new_from_file(fileobj, headers_only=False):
25
    """
26
    Create a new GRIB message from file.
27
    
28
    Parameters:
29
    - fileobj: File object opened in binary mode
30
    - headers_only (bool): Read only headers if True
31
    
32
    Returns:
33
    int: Message handle ID or None if no more messages
34
    """
35

36
def codes_bufr_new_from_file(fileobj, headers_only=False):
37
    """
38
    Create a new BUFR message from file.
39
    
40
    Parameters:
41
    - fileobj: File object opened in binary mode  
42
    - headers_only (bool): Read only headers if True
43
    
44
    Returns:
45
    int: Message handle ID or None if no more messages
46
    """
47

48
def codes_any_new_from_file(fileobj, headers_only=False):
49
    """
50
    Create a new message from file (auto-detect format).
51
    
52
    Parameters:
53
    - fileobj: File object opened in binary mode
54
    - headers_only (bool): Read only headers if True
55
    
56
    Returns:
57
    int: Message handle ID or None if no more messages
58
    """
59

60
def codes_metar_new_from_file(fileobj, headers_only=False):
61
    """Create a new METAR message from file."""
62

63
def codes_gts_new_from_file(fileobj, headers_only=False):
64
    """Create a new GTS message from file."""
65
```
66

67
### Creating Messages from Templates
68

69
Create new messages from predefined samples or templates.
70

71
```python { .api }
72
def codes_new_from_samples(samplename, product_kind):
73
    """
74
    Create a new message from sample with explicit product type.
75
    
76
    Parameters:
77
    - samplename (str): Name of sample template
78
    - product_kind (int): Message type (CODES_PRODUCT_GRIB, CODES_PRODUCT_BUFR, etc.)
79
    
80
    Returns:
81
    int: Message handle ID
82
    """
83

84
def codes_grib_new_from_samples(samplename):
85
    """
86
    Create a new GRIB message from sample.
87
    
88
    Parameters:
89
    - samplename (str): Name of sample template
90
    
91
    Returns:
92
    int: Message handle ID
93
    """
94

95
def codes_bufr_new_from_samples(samplename):
96
    """
97
    Create a new BUFR message from sample.
98
    
99
    Parameters:
100
    - samplename (str): Name of sample template
101
    
102
    Returns:
103
    int: Message handle ID
104
    """
105

106
def codes_any_new_from_samples(samplename):
107
    """
108
    Create a new message from sample (auto-detect format).
109
    
110
    Parameters:
111
    - samplename (str): Name of sample template
112
    
113
    Returns:
114
    int: Message handle ID
115
    """
116
```
117

118
### Creating Messages from Data
119

120
Create messages from existing message data or index entries.
121

122
```python { .api }
123
def codes_new_from_message(message):
124
    """
125
    Create a new message from binary message data.
126
    
127
    Parameters:
128
    - message (bytes): Binary message data
129
    
130
    Returns:
131
    int: Message handle ID
132
    """
133

134
def codes_new_from_index(indexid):
135
    """
136
    Create a new message from index entry.
137
    
138
    Parameters:
139
    - indexid (int): Index handle ID
140
    
141
    Returns:
142
    int: Message handle ID
143
    """
144
```
145

146
### Message Management
147

148
Handle message lifecycle, cloning, and memory management.
149

150
```python { .api }
151
def codes_release(msgid):
152
    """
153
    Release message from memory.
154
    
155
    Parameters:
156
    - msgid (int): Message handle ID
157
    """
158

159
def codes_clone(msgid_src, headers_only=False):
160
    """
161
    Clone/copy a message.
162
    
163
    Parameters:
164
    - msgid_src (int): Source message handle ID
165
    - headers_only (bool): Clone only headers if True
166
    
167
    Returns:
168
    int: New message handle ID
169
    """
170
```
171

172
### File Operations
173

174
Count messages and handle file-level operations.
175

176
```python { .api }
177
def codes_count_in_file(fileobj):
178
    """
179
    Count total messages in file.
180
    
181
    Parameters:
182
    - fileobj: File object opened in binary mode
183
    
184
    Returns:
185
    int: Number of messages in file
186
    """
187

188
def codes_write(msgid, fileobj):
189
    """
190
    Write message to file.
191
    
192
    Parameters:
193
    - msgid (int): Message handle ID
194
    - fileobj: File object opened in binary write mode
195
    """
196
```
197

198
### Message Information
199

200
Get message metadata and binary representation.
201

202
```python { .api }
203
def codes_get_message_size(msgid):
204
    """
205
    Get message size in bytes.
206
    
207
    Parameters:
208
    - msgid (int): Message handle ID
209
    
210
    Returns:
211
    int: Message size in bytes
212
    """
213

214
def codes_get_message_offset(msgid):
215
    """
216
    Get message offset in file.
217
    
218
    Parameters:
219
    - msgid (int): Message handle ID
220
    
221
    Returns:
222
    int: Message offset in bytes
223
    """
224

225
def codes_get_message(msgid):
226
    """
227
    Get message as binary data.
228
    
229
    Parameters:
230
    - msgid (int): Message handle ID
231
    
232
    Returns:
233
    bytes: Binary message data
234
    """
235
```
236

237
## Usage Examples
238

239
### Reading All Messages from a File
240

241
```python
242
import eccodes
243

244
with open('forecast.grib', 'rb') as f:
245
    while True:
246
        msg = eccodes.codes_grib_new_from_file(f)
247
        if msg is None:
248
            break
249
        
250
        # Process message
251
        param = eccodes.codes_get(msg, 'paramId')
252
        level = eccodes.codes_get(msg, 'level')
253
        print(f"Parameter {param} at level {level}")
254
        
255
        # Clean up
256
        eccodes.codes_release(msg)
257
```
258

259
### Creating and Writing a New Message
260

261
```python
262
import eccodes
263

264
# Create from sample template
265
msg = eccodes.codes_grib_new_from_samples('regular_ll_sfc_grib2')
266

267
# Modify message parameters
268
eccodes.codes_set(msg, 'paramId', 130)  # Temperature
269
eccodes.codes_set(msg, 'level', 850)    # 850 hPa level
270

271
# Write to file
272
with open('output.grib', 'wb') as f:
273
    eccodes.codes_write(msg, f)
274

275
# Clean up
276
eccodes.codes_release(msg)
277
```
278

279
### Format Detection and Multi-Format Processing
280

281
```python
282
import eccodes
283

284
with open('mixed_data.dat', 'rb') as f:
285
    while True:
286
        msg = eccodes.codes_any_new_from_file(f)
287
        if msg is None:
288
            break
289
            
290
        # Determine format
291
        product_kind = eccodes.codes_get(msg, 'productKind')
292
        if product_kind == eccodes.CODES_PRODUCT_GRIB:
293
            print("Processing GRIB message")
294
        elif product_kind == eccodes.CODES_PRODUCT_BUFR:
295
            print("Processing BUFR message")
296
            
297
        eccodes.codes_release(msg)
298
```